(Версии dbt: v2.0 и новее) # Подключение Databricks к dbt v2 Локальная разработка Вы можете настроить адаптер Databricks, выполнив `dbt init` в интерфейсе командной строки (CLI) или вручную создав файл `profiles.yml` с полями, настроенными для вашего типа аутентификации. Адаптер Databricks для dbt v2 поддерживает следующие [способы аутентификации](#supported-authentication-types): * Персональный токен доступа (для отдельных пользователей) * Токен сервисного принципала (для служебных пользователей) * OAuth * Федерация токенов OAuth с использованием OIDC ## Разрешения на доступ к хранилищу для dbt v2 Пользователь или субъект-служба Databricks, от имени которого работает dbt v2, должен иметь привилегии для каталога и схем, в которых выполняются модели, а также права доступа, необходимые для запросов метаданных. Требования зависят от того, используете ли вы Unity Catalog или устаревший Hive Metastore. ### Необходимые объекты Databricks Перед подключением следующие объекты должны существовать или быть доступны: | Объект | Назначение | | ----------------------------------- | ---------------------------------------------------- | | **Рабочая область** | URL вашей рабочей области Databricks (host) | | **SQL warehouse или кластер** | Вычислительный ресурс (с использованием `http_path`) | | **Каталог** | Каталог Unity Catalog или Hive Metastore | | **Схема** | Целевая схема в каталоге | | **Пользователь или субъект-служба** | Учетная запись для аутентификации | ### Unity Catalog Необходимые права доступа для Unity Catalog: | Разрешение | Объект | Назначение | | --------------- | ------------------------- | -------------------------------------------------------- | | `USE CATALOG` | Каталог | Доступ к каталогу | | `USE SCHEMA` | Схема | Доступ к схемам | | `SELECT` | Таблицы или представления | Чтение существующих данных и источников | | `CREATE TABLE` | Схема | Создание моделей, материализованных в виде таблиц | | `CREATE VIEW` | Схема | Создание моделей, материализованных в виде представлений | | `MODIFY` | Таблицы | Вставка, обновление и удаление данных | | `CREATE SCHEMA` | Каталог | Автоматическое создание схем (при необходимости) | ### Hive Metastore Необходимые права доступа для устаревшего Hive Metastore: | Разрешение | Объект | Назначение | | ---------- | ----------- | ------------------------------- | | `USAGE` | База данных | Доступ к базе данных | | `SELECT` | Таблицы | Чтение данных | | `CREATE` | База данных | Создание таблиц и представлений | | `MODIFY` | Таблицы | Изменение данных | ### Операции с метаданными Для основных функций dbt необходимы следующие права: | Тип запроса | Используемый SQL | Необходимое разрешение | | ----------------------------------- | ----------------------------------------------------------------- | ---------------------------- | | Получение схемы таблицы | `DESCRIBE TABLE` или `DESCRIBE TABLE EXTENDED` | SELECT для таблицы | | Получение схемы таблицы (DBR 16.2+) | `DESCRIBE TABLE EXTENDED ... AS JSON` | SELECT для таблицы | | Получение списка отношений | Запрос к `INFORMATION_SCHEMA.TABLES` | USE CATALOG и USE SCHEMA | | Проверка актуальности источника | Запрос к `INFORMATION_SCHEMA.TABLES` для получения `last_altered` | USE CATALOG | | Получение определения представления | Запрос к `SYSTEM.INFORMATION_SCHEMA.VIEWS` | Доступ к системному каталогу | | Создание схем | `CREATE SCHEMA IF NOT EXISTS` | CREATE SCHEMA для каталога | ### Модели Python Дополнительные разрешения для сред, использующих модели Python | Разрешение | Объект | Назначение | | ---------------------------- | ------------------------- | -------------------------------- | | Доступ к API рабочей области | `/api/2.0/workspace/*` | Создание каталогов для блокнотов | | Импорт блокнотов | Рабочая область | Импорт блокнотов Python | | Выполнение заданий | Кластер или SQL warehouse | Запуск моделей Python | ## Сведения о настройке Databricks Адаптер `dbt-databricks` для dbt v2 — единственный поддерживаемый способ подключения к Databricks. `dbt-databricks` может подключаться к хранилищам Databricks SQL Warehouse. Эти хранилища рекомендуется использовать для начала работы с Databricks. Подробнее о получении учетных данных для настройки профиля см. в [документации Databricks](https://docs.databricks.com/dev-tools/dbt.html#). ## Настройка dbt v2 При выполнении `dbt init` в CLI вам будет предложено заполнить следующие поля: * **Host:** Имя хоста экземпляра Databricks (без префикса `http` или `https`) * **HTTP Path:** Путь к вашему SQL-серверу или кластеру * **Schema:** Схема проекта для разработки, промежуточной среды или развертывания * **Catalog (необязательно):** Каталог Databricks, содержащий ваши схемы и таблицы Кроме того, вы можете вручную создать файл `profiles.yml` и настроить поля. Примеры форматирования см. в разделе [аутентификации](#supported-authentication-types). Если файл `profiles.yml` уже существует, вам будет предложено сохранить существующие поля или перезаписать их. Затем выберите способ аутентификации. Следуйте инструкциям на экране, чтобы указать необходимые сведения. ## Поддерживаемые типы аутентификации ### Personal access token Введите свой персональный токен доступа (PAT) для среды Databricks. Подробнее о получении PAT см. в [документации Databricks](https://docs.databricks.com/aws/en/dev-tools/auth/pat). Databricks считает эту возможность устаревшей и рекомендует использовать OAuth вместо PAT. #### Пример настройки с персональным токеном доступа profiles.yml ```yaml default: target: dev outputs: dev: type: databricks database: TRANSFORMING schema: JANE_SMITH host: YOUR.HOST.COM http_path: YOUR/PATH/HERE token: ABC123 auth_type: databricks_cli threads: 16 ``` ### Service Principal token Введите токен сервисного принципала для среды Databricks. Подробнее о получении токена сервисного принципала см. в [документации Databricks](https://docs.databricks.com/aws/en/admin/users-groups/service-principals). #### Пример настройки с токеном сервисного принципала profiles.yml ```yaml default: target: dev outputs: dev: type: databricks database: TRANSFORMING schema: JANE_SMITH host: YOUR.HOST.COM http_path: YOUR/PATH/HERE token: ABC123 auth_type: databricks_cli threads: 16 ``` ### OAuth (Recommended) При выборе OAuth будет создано подключение к вашей среде Databricks и откроется веб-браузер для завершения аутентификации. Пользователям потребуется повторно проходить аутентификацию при запуске каждого нового сеанса dbt. #### Пример настройки OAuth profiles.yml ```yaml default: target: dev outputs: dev: type: databricks database: TRANSFORMING schema: JANE_SMITH host: YOUR.HOST.COM http_path: YOUR/PATH/HERE auth_type: oauth threads: 16 ``` ### OAuth token federation Для использования федерации токенов OAuth можно передать токен OIDC через переменную окружения или файл. #### Пример настройки OIDC с использованием переменной окружения Чтобы передать токен OIDC через переменную окружения, задайте `auth_type: env-oidc` в `profiles.yml` и укажите токен OIDC в `DATABRICKS_OIDC_TOKEN`. profiles.yml ```yaml target: dev outputs: dev: type: databricks database: TRANSFORMING schema: JANE_SMITH host: YOUR.HOST.COM http_path: YOUR/PATH/HERE auth_type: env-oidc client_id: CLIENT_ID threads: 16 ``` #### Пример настройки OIDC с использованием файла токена Чтобы передать токен OIDC через файл токена, задайте `auth_type: file-oidc` в `profiles.yml` и укажите путь к файлу в `oidc_token_filepath`. Вместо этого можно не указывать `oidc_token_filepath` в `profiles.yml`, а задать путь в переменной окружения `DATABRICKS_OIDC_TOKEN_FILE` или `DATABRICKS_OIDC_TOKEN_FILEPATH`. dbt использует переменную окружения, только если `oidc_token_filepath` отсутствует в `profiles.yml`. Если заданы оба значения, dbt использует только настройку из `profiles.yml` и никогда не обращается к переменной окружения в качестве запасного варианта. Мы рекомендуем задавать путь в `profiles.yml`. profiles.yml ```yaml default: target: dev outputs: dev: type: databricks database: TRANSFORMING schema: JANE_SMITH host: YOUR.HOST.COM http_path: YOUR/PATH/HERE auth_type: file-oidc client_id: CLIENT_ID oidc_token_filepath: PATH/TO/TOKEN/FILE threads: 16 ``` ## Необязательные настройки подключения Добавьте эти необязательные поля в настройки подключения Databricks в `profiles.yml`, чтобы управлять временем ожидания подключения и повторными попытками. | Поле профиля | Описание | Значение по умолчанию | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `connect_timeout` | Сколько секунд dbt ожидает подключения к Databricks, прежде чем прекратить попытку. Укажите число больше `0`, иначе dbt вернет ошибку. Например, `600` означает 600 секунд (10 минут). Увеличьте это значение, если ваши задания запускаются, пока SQL-хранилище еще запускается. | `200` | | `connect_retries` | Количество повторных попыток подключения к Databricks после неудачной первой попытки. Повторная попытка выполняется, только если Databricks помечает ошибку как допускающую повторную попытку или если `retry_all` имеет значение `true`. | `1` | | `retry_all` | Установите `true`, чтобы повторять попытки при любой ошибке подключения. Установите `false`, чтобы повторять попытки только при ошибках, которые Databricks помечает как допускающие повторную попытку. | `false` | Эти настройки применяются только к установлению подключения. Они не обеспечивают повторное выполнение запросов, завершившихся ошибкой после подключения dbt. #### Пример В следующем примере для `connect_timeout` задано значение `600` (10 минут), чтобы dbt мог дождаться запуска SQL-хранилища. profiles.yml ```yaml outputs: dev: type: databricks # ...остальные поля подключения connect_timeout: 600 ``` ## Дополнительная информация Информацию о настройках, специфичных для Databricks, см. в [справочном руководстве по адаптеру Databricks](https://docs.getdbt.tech/reference/resource-configs/databricks-configs.md).