Подключение BigQuery
Необходимые разрешения
Учетным записям пользователей dbt требуются следующие разрешения для чтения данных, а также для создания таблиц и views в проекте BigQuery:
- Редактор данных BigQuery
- Пользователь BigQuery
Для BigQuery с dbt Fusion Engine пользователям также требуется:
- Пользователь сеансов чтения BigQuery (для доступа к Storage Read API)
Для работы с BigQuery DataFrames пользователям необходимы дополнительные разрешения:
- Пользователь заданий BigQuery
- Пользователь сеансов чтения BigQuery
- Пользователь среды выполнения Notebook
- Создатель кода
- colabEnterpriseUser
Аутентификация
dbt поддерживает различные методы аутентификации в зависимости от вашего окружения и типа плана:
- Окружения для разработки поддерживают:
- Service JSON
- BigQuery OAuth Enterprise
- Окружения для деплоя поддерживают:
- Service JSON
- BigQuery Workload Identity Federation (WIF) Enterprise
Эти методы аутентификации настраиваются в глобальных настройках подключений аккаунта, а не в настройках единого входа (SSO) или интеграций.
При создании нового подключения BigQuery вам будет предложено два варианта схемы подключения (оба используют один и тот же адаптер):
- BigQuery: Поддерживает все типы подключений (используйте этот вариант)
- BigQuery (Legacy): Поддерживает все типы подключений, кроме WIF (устаревшая функциональность. Не использовать)
Все новые подключения должны использовать вариант BigQuery, так как BigQuery (Legacy) будет выведен из эксплуатации. Чтобы обновить существующие подключения и учетные данные в окружении и перейти на новый вариант BigQuery, сначала используйте API для удаления текущих конфигураций.
JSON keyfile
Хотя поля в подключении BigQuery можно заполнить вручную, мы рекомендуем загрузить keyfile сервисного аккаунта JSON, чтобы быстро и корректно настроить подключение к BigQuery.
Вы можете предоставить JSON ключевой файл в одном из двух форматов:
- JSON keyfile upload — Загрузите keyfile напрямую в его стандартном формате JSON.
- Base64-encoded string — Укажите keyfile в виде строки, закодированной в base64. При предоставлении строки в формате base64 dbt автоматически декодирует её и заполняет необходимые поля.
Опция JSON keyfile доступна для настройки как development, так и deployment окружений.
Загрузка корректного JSON keyfile заполнит следующие поля:
- Project ID
- Private key ID
- Private key
- Client email
- Client ID
- Auth URI
- Token URI
- Auth provider x509 cert url
- Client x509 cert url
В дополнение к этим полям, в подключении BigQuery можно настроить ещё два необязательных поля:
| Loading table... |
BigQuery OAuth
Доступно в: средах разработки, только в планах Enterprise
Метод аутентификации OAuth позволяет dbt выполнять запросы от имени пользователя BigQuery или рабочей нагрузки, не сохраняя ключевой файл сервисного аккаунта BigQuery в dbt. При этом JSON всё равно должен быть предоставлен, либо соответствующие поля должны быть заполнены вручную, чтобы завершить настройку в dbt Cloud. Эти значения не обязательно должны быть реальными для работы данного обходного механизма (например, можно указать N/A). Подробнее о первоначальной настройке подключения BigQuery OAuth в dbt см. в документации по настройке BigQuery OAuth.
Если вы являетесь конечным пользователем и в вашей организации настроен BigQuery OAuth, вы можете связать проект со своей личной учетной записью BigQuery в разделе Profile в dbt.
Федерация удостоверений рабочей нагрузки BigQuery EnterprisePreview
Если вы используете BigQuery WIF, мы рекомендуем использовать его вместе с BigQuery OAuth. В противном случае вам потребуется создать два подключения — одно с service JSON и одно с WIF, чтобы использовать service JSON для сред разработки.
Доступно в: средах развертывания
Метод аутентификации BigQuery WIF позволяет dbt выполнять запросы в средах развертывания от имени сервисного аккаунта без настройки ключевого файла сервисного аккаунта BigQuery в dbt. Подробнее о первоначальной настройке подключения BigQuery WIF в dbt см. в документации по настройке BigQuery WIF.
Конфигурация
Чтобы узнать, как оптимизировать производительность с помощью конфигураций, специфичных для конкретной платформы данных, в dbt, обратитесь к разделу BigQuery-specific configuration.
Необязательные конфигурации
В BigQuery необязательные конфигурации позволяют настроить параметры для таких задач, как приоритет запросов, местоположение набора данных, время ожидания выполнения задания и многое другое. Эти опции дают вам больший контроль над тем, как BigQuery работает за кулисами, чтобы соответствовать вашим требованиям.
Чтобы настроить дополнительные параметры в dbt:
- Нажмите на имя своей учетной записи в левом нижнем меню и перейдите в Account settings > Projects.
- Выберите свой проект BigQuery.
- Перейдите в Development connection и выберите BigQuery.
- Нажмите Edit, затем прокрутите вниз до раздела Optional settings.
Ниже перечислены необязательные параметры конфигурации, которые вы можете задать в dbt:
| Loading table... |
Запуск моделей dbt на Python в Google Cloud Platform
Для выполнения Python-моделей dbt на GCP, dbt использует вспомогательные сервисы, Dataproc и Cloud Storage, которые предлагают тесную интеграцию с BigQuery. Вы можете использовать существующий кластер Dataproc и корзину Cloud Storage или создать новые:
- https://cloud.google.com/dataproc/docs/guides/create-cluster
- https://cloud.google.com/storage/docs/creating-buckets
Подключения и управление учетными данными на уровне аккаунта
Вы можете повторно использовать подключения в нескольких проектах с помощью глобальных подключений. Подключения привязаны на уровне среды (ранее на уровне проекта), поэтому вы можете использовать несколько подключений внутри одного проекта (для управления разработкой, тестированием, производством и т.д.).
Подключения BigQuery в dbt в настоящее время предполагают, что учетные данные (credentials) настраиваются на уровне подключения (и это относится только к подключениям BigQuery). Изначально это было реализовано для упрощения создания нового подключения путем загрузки keyfile сервисного аккаунта.
В этом разделе описывается, как переопределить учетные данные на уровне окружения с помощью extended attributes, чтобы администраторы проекта могли управлять учетными данными независимо от параметров подключения на уровне аккаунта, используемых для данного окружения.
Для проекта вы сначала создадите переменную среды для хранения секретного значения private_key. Затем вы используете расширенные атрибуты, чтобы переопределить весь JSON учетной записи службы (вы не можете переопределить только секретный ключ из-за ограничения расширенных атрибутов).
- Новая переменная среды
- Создайте новую секретную переменную окружения для хранения приватного ключа:
DBT_ENV_SECRET_PROJECTXXX_PRIVATE_KEY - Заполните значение приватного ключа в соответствии с используемым окружением
Чтобы автоматизировать развертывание, используйте следующий запрос к admin API, где XXXXX — номер вашего аккаунта, YYYYY — номер вашего проекта, а ZZZZZ — ваш API token:
curl --request POST \
--url https://cloud.getdbt.com/api/v3/accounts/XXXXX/projects/YYYYY/environment-variables/bulk/ \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ZZZZZ' \
--header 'Content-Type: application/json' \
--data '{
"env_var": [
{
"new_name": "DBT_ENV_SECRET_PROJECTXXX_PRIVATE_KEY",
"project": "Value by default for the entire project",
"ENVIRONMENT_NAME_1": "Optional, if wanted, value for environment name 1",
"ENVIRONMENT_NAME_2": "Optional, if wanted, value for environment name 2"
}
]
}'
-
Расширенные атрибуты
В деталях среды заполните блок расширенных атрибутов следующим содержимым (заменив
XXXна вашу соответствующую информацию):keyfile_json:
type: service_account
project_id: xxx
private_key_id: xxx
private_key: '{{ env_var(''DBT_ENV_SECRET_PROJECTXXX_PRIVATE_KEY'') }}'
client_email: xxx
client_id: xxx
auth_uri: xxx
token_uri: xxx
auth_provider_x509_cert_url: xxx
client_x509_cert_url: xxxЕсли вам нужно переопределить другие поля на уровне среды через расширенные атрибуты, пожалуйста, соблюдайте ожидаемую отступы (порядок не имеет значения):
priority: interactive
keyfile_json:
type: xxx
project_id: xxx
private_key_id: xxx
private_key: '{{ env_var(''DBT_ENV_SECRET_PROJECTXXX_PRIVATE_KEY'') }}'
client_email: xxx
client_id: xxx
auth_uri: xxx
token_uri: xxx
auth_provider_x509_cert_url: xxx
client_x509_cert_url: xxx
execution_project: buck-stops-here-456
Чтобы автоматизировать деплой, сначала необходимо создать payload расширенных атрибутов для конкретного проекта, а затем назначить его определённому окружению. Где XXXXX — это номер вашего аккаунта, YYYYY — номер проекта, а ZZZZZ — ваш API‑токен:
curl --request POST \
--url https://cloud.getdbt.com/api/v3/accounts/XXXXX/projects/YYYYY/extended-attributes/ \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ZZZZZ' \
--header 'Content-Type: application/json' \
--data '{
"id": null,
"extended_attributes": {"type":"service_account","project_id":"xxx","private_key_id":"xxx","private_key":"{{ env_var('DBT_ENV_SECRET_PROJECTXXX_PRIVATE_KEY') }}","client_email":"xxx","client_id":xxx,"auth_uri":"https://accounts.google.com/o/oauth2/auth","token_uri":"https://oauth2.googleapis.com/token","auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs","client_x509_cert_url":"xxx"},
"state": 1
}'
Запомните id, возвращенный в сообщении. Он будет использован в следующем вызове. С EEEEE идентификатором среды, FFFFF идентификатором расширенных атрибутов:
curl --request POST \
--url https://cloud.getdbt.com/api/v3/accounts/XXXXX/projects/YYYYY/environments/EEEEE/ \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ZZZZZZ' \
--header 'Content-Type: application/json' \
--data '{
"extended_attributes_id": FFFFF
}'

