# Подключение Teradata к dbt v1 Локальная разработка Некоторые базовые функции могут быть ограничены. Если вы хотите внести свой вклад в разработку, ознакомьтесь с исходным кодом в репозитории, указанном в следующем разделе. Файл `profiles.yml` нужен только для dbt v1 и dbt v2 Если вы используете dbt platform, создавать файл `profiles.yml` не нужно. Этот файл необходим только при локальном использовании v1 или v2. Подробнее о предварительных требованиях для v2 см. в разделе [Поддерживаемые возможности](https://docs.getdbt.tech/docs/dbt/supported-features.md). Чтобы подключить вашу платформу данных к dbt, см. раздел [О платформах данных](https://docs.getdbt.tech/docs/platform/connect-data-platform/about-connections.md). * **Поддерживается**: Teradata * **Авторы**: Teradata * **Репозиторий GitHub**: [Teradata/dbt-teradata](https://github.com/Teradata/dbt-teradata) [![](https://img.shields.io/github/stars/Teradata/dbt-teradata?style=for-the-badge)](https://github.com/Teradata/dbt-teradata) * **Пакет PyPI**: `dbt-teradata` [![](https://badge.fury.io/py/dbt-teradata.svg)](https://badge.fury.io/py/dbt-teradata) * **Канал Slack**: [#db-teradata](https://getdbt.slack.com/archives/C027B6BHMT3) * **Поддерживаемая версия dbt**: v0.21.0 и новее * **Поддержка dbt**: Supported * **Минимальная версия платформы данных**: n/a ## Установка dbt-teradata Установите адаптер с помощью \`pip\`: `python -m pip install dbt-teradata` ## Настройка dbt-teradata Конфигурацию, специфичную для Teradata, см. на странице [настроек Teradata.](https://docs.getdbt.tech/reference/resource-configs/teradata-configs.md) ## Совместимость с Python | Версия плагина | Python 3.9 | Python 3.10 | Python 3.11 | Python 3.12 | Python 3.13 | | -------------- | ---------- | ----------- | ----------- | ----------- | ----------- | | 1.0.0.x | ✅ | ❌ | ❌ | ❌ | ❌ | | 1.1.x.x | ✅ | ✅ | ❌ | ❌ | ❌ | | 1.2.x.x | ✅ | ✅ | ❌ | ❌ | ❌ | | 1.3.x.x | ✅ | ✅ | ❌ | ❌ | ❌ | | 1.4.x.x | ✅ | ✅ | ✅ | ❌ | ❌ | | 1.5.x | ✅ | ✅ | ✅ | ❌ | ❌ | | 1.6.x | ✅ | ✅ | ✅ | ❌ | ❌ | | 1.7.x | ✅ | ✅ | ✅ | ❌ | ❌ | | 1.8.x | ✅ | ✅ | ✅ | ✅ | ❌ | | 1.9.x | ✅ | ✅ | ✅ | ✅ | ❌ | | 1.10.x | ✅ | ✅ | ✅ | ✅ | ✅ | ## Совместимость версий зависимых пакетов dbt | dbt-teradata | dbt v1 | dbt-teradata-util | dbt-util | | ------------ | ------ | ----------------- | -------------- | | 1.2.x | 1.2.x | 0.1.0 | 0.9.x or below | | 1.6.7 | 1.6.7 | 1.1.1 | 1.1.1 | | 1.7.x | 1.7.x | 1.1.1 | 1.1.1 | | 1.8.x | 1.8.x | 1.1.1 | 1.1.1 | | 1.8.x | 1.8.x | 1.2.0 | 1.2.0 | | 1.8.x | 1.8.x | 1.3.0 | 1.3.0 | | 1.9.x | 1.9.x | 1.3.0 | 1.3.0 | | 1.10.x | 1.10.x | 1.3.0 | 1.3.0 | ### Подключение к Teradata ### Подключение к Teradata Чтобы подключиться к Teradata Vantage из dbt, необходимо добавить [профиль](https://docs.getdbt.tech/docs/local/profiles.yml.md) в файл `profiles.yml`. Профиль Teradata имеет следующий синтаксис: profiles.yml ```yaml : target: outputs: : type: teradata user: password: schema: tmode: ANSI threads: [optional, 1 or more] #optional fields ``` #### Описание полей профиля Teradata Следующие поля являются обязательными: | Параметр | По умолчанию | Тип | Описание | | ---------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------- | | `user` | | строка | Указывает имя пользователя базы данных. Эквивалентно параметру подключения `USER` драйвера Teradata JDBC. | | `password` | | строка | Указывает пароль базы данных. Эквивалентно параметру подключения `PASSWORD` драйвера Teradata JDBC. | | `schema` | | строка | Указывает начальную базу данных для использования после входа, вместо базы данных по умолчанию для пользователя. | | `tmode` | `"ANSI"` | строка | Указывает режим транзакции. В настоящее время поддерживается только режим `ANSI`. | Плагин также поддерживает следующие необязательные параметры подключения: | Параметр | По умолчанию | Тип | Описание | | --------------------- | -------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account` | | string | Указывает учетную запись базы данных. Эквивалентно параметру подключения `ACCOUNT` драйвера Teradata JDBC. | | `browser` | | string | Указывает команду для открытия браузера при Browser Authentication, когда `logmech` имеет значение `BROWSER`. Browser Authentication поддерживается в Windows и macOS. Эквивалентно параметру подключения `BROWSER` драйвера Teradata JDBC. | | `browser_tab_timeout` | `"5"` | quoted integer | Указывает количество секунд ожидания перед закрытием вкладки браузера после завершения Browser Authentication. Значение по умолчанию — 5 секунд. Поведение зависит от браузера, и не все браузеры поддерживают автоматическое закрытие вкладок. | | `browser_timeout` | `"180"` | quoted integer | Указывает количество секунд, в течение которых драйвер ожидает завершения Browser Authentication. Значение по умолчанию — 180 секунд (3 минуты). | | `column_name` | `"false"` | quoted boolean | Управляет поведением элементов `name` в последовательности `.description` курсора. Эквивалентно параметру подключения `COLUMN_NAME` драйвера Teradata JDBC. Значение `false` указывает, что элемент `name` в `.description` возвращает имя из AS‑клаузы, если оно доступно, либо имя столбца, либо заголовок столбца. Значение `true` указывает, что элемент `name` возвращает имя столбца, если оно доступно, но не оказывает эффекта, когда поддержка StatementInfo parcel недоступна. | | `connect_timeout` | `"10000"` | quoted integer | Указывает тайм-аут в миллисекундах для установления TCP‑соединения. Укажите 0 для отсутствия тайм-аута. Значение по умолчанию — 10 секунд (10000 миллисекунд). | | `cop` | `"true"` | quoted boolean | Указывает, выполняется ли обнаружение COP. Эквивалентно параметру подключения `COP` драйвера Teradata JDBC. | | `coplast` | `"false"` | quoted boolean | Указывает, каким образом обнаружение COP определяет последний hostname COP. Эквивалентно параметру подключения `COPLAST` драйвера Teradata JDBC. Когда `coplast` имеет значение `false` или не задан, либо обнаружение COP отключено, DNS‑запрос для hostname coplast не выполняется. Когда `coplast` имеет значение `true` и обнаружение COP включено, выполняется DNS‑запрос для hostname coplast. | | `port` | `"1025"` | quoted integer | Указывает номер порта базы данных. Эквивалентно параметру подключения `DBS_PORT` драйвера Teradata JDBC. | | `encryptdata` | `"false"` | quoted boolean | Управляет шифрованием данных, передаваемых между драйвером и базой данных. Эквивалентно параметру подключения `ENCRYPTDATA` драйвера Teradata JDBC. | | `fake_result_sets` | `"false"` | quoted boolean | Управляет тем, будет ли фиктивный набор результатов, содержащий метаданные запроса, предшествовать каждому реальному набору результатов. | | `field_quote` | `"\""` | string | Указывает строку из одного символа, используемую для экранирования полей в CSV‑файле. | | `field_sep` | `","` | string | Указывает строку из одного символа, используемую в качестве разделителя полей в CSV‑файле. Эквивалентно параметру подключения `FIELD_SEP` драйвера Teradata JDBC. | | `host` | | string | Указывает имя хоста базы данных. | | `https_port` | `"443"` | quoted integer | Указывает номер порта базы данных для HTTPS/TLS‑соединений. Эквивалентно параметру подключения `HTTPS_PORT` драйвера Teradata JDBC. | | `lob_support` | `"true"` | quoted boolean | Управляет поддержкой LOB. Эквивалентно параметру подключения `LOB_SUPPORT` драйвера Teradata JDBC. | | `log` | `"0"` | quoted integer | Управляет отладочным логированием. Частично эквивалентно параметру подключения `LOG` драйвера Teradata JDBC. Поведение этого параметра может измениться в будущем. В настоящее время значение параметра задается целым числом, где бит 1 отвечает за трассировку функций и методов, бит 2 — за отладочное логирование, бит 4 — за hex‑дампы передаваемых и принимаемых сообщений, а бит 8 — за тайминги. Значение формируется путем суммирования 1, 2, 4 и/или 8. | | `logdata` | | string | Указывает дополнительные данные для выбранного метода аутентификации при входе. Эквивалентно параметру подключения `LOGDATA` драйвера Teradata JDBC. | | `logon_timeout` | `"0"` | quoted integer | Указывает тайм-аут входа в систему в секундах. Ноль означает отсутствие тайм-аута. | | `logmech` | `"TD2"` | string | Указывает метод аутентификации при входе. Эквивалентно параметру подключения `LOGMECH` драйвера Teradata JDBC. Возможные значения: `TD2` (по умолчанию), `JWT`, `LDAP`, `BROWSER`, `KRB5` (Kerberos) или `TDNEGO`. | | `max_message_body` | `"2097000"` | quoted integer | Указывает максимальный размер Response Message в байтах. Эквивалентно параметру подключения `MAX_MESSAGE_BODY` драйвера Teradata JDBC. | | `partition` | `"DBC/SQL"` | string | Указывает раздел базы данных. Эквивалентно параметру подключения `PARTITION` драйвера Teradata JDBC. | | `request_timeout` | `"0"` | quoted integer | Указывает тайм-аут выполнения каждого SQL‑запроса. Ноль означает отсутствие тайм-аута. | | `retries` | `0` | integer | Позволяет адаптеру автоматически повторять попытку при возникновении временной, редко возникающей ошибки при открытии нового соединения с базой данных. Этот параметр может быть задан с помощью конфигурации `retries`. Значение по умолчанию — 0. Период ожидания между попытками подключения по умолчанию составляет одну секунду. Параметр `retry_timeout` (в секундах) позволяет изменить этот интервал ожидания. | | `runstartup` | "false" | quoted boolean | Управляет тем, выполняется ли пользовательский SQL‑запрос STARTUP после входа в систему. Для получения дополнительной информации см. User STARTUP SQL Request. Эквивалентно параметру подключения `RUNSTARTUP` драйвера Teradata JDBC. Если `retries` установлен в 3, адаптер попытается установить новое соединение три раза при возникновении ошибки. | | `sessions` | | quoted integer | Указывает количество соединений передачи данных для FastLoad или FastExport. Значение по умолчанию (рекомендуемое) позволяет базе данных выбрать подходящее количество соединений. Эквивалентно параметру подключения `SESSIONS` драйвера Teradata JDBC. | | `sip_support` | `"true"` | quoted boolean | Управляет использованием StatementInfo parcel. Эквивалентно параметру подключения `SIP_SUPPORT` драйвера Teradata JDBC. | | `sp_spl` | `"true"` | quoted boolean | Управляет тем, сохраняется ли исходный код хранимой процедуры в базе данных при создании SQL‑хранимой процедуры. Эквивалентно параметру подключения `SP_SPL` драйвера Teradata JDBC. | | `sslca` | | string | Указывает имя файла PEM, содержащего сертификаты центра сертификации (CA), для использования со значениями `sslmode` `VERIFY-CA` или `VERIFY-FULL`. Эквивалентно параметру подключения `SSLCA` драйвера Teradata JDBC. | | `sslcrc` | `"ALLOW"` | string | Эквивалентно параметру подключения `SSLCRC` драйвера Teradata JDBC. Значения не чувствительны к регистру.
• `ALLOW` обеспечивает «мягкий отказ», при котором сбои связи игнорируются во время проверки отзыва сертификатов.
• `REQUIRE` требует успешного выполнения проверки отзыва сертификатов. | | `sslcapath` | | string | Указывает каталог с PEM‑файлами, содержащими сертификаты центра сертификации (CA), для использования со значениями `sslmode` `VERIFY-CA` или `VERIFY-FULL`. Используются только файлы с расширением `.pem`. Другие файлы в указанном каталоге не используются. Эквивалентно параметру подключения `SSLCAPATH` драйвера Teradata JDBC. | | `sslcipher` | | string | Указывает TLS‑шифр для HTTPS/TLS‑соединений. Эквивалентно параметру подключения `SSLCIPHER` драйвера Teradata JDBC. | | `sslmode` | `"PREFER"` | string | Указывает режим подключения к базе данных. Эквивалентно параметру подключения `SSLMODE` драйвера Teradata JDBC.
• `DISABLE` отключает HTTPS/TLS‑соединения и использует только соединения без TLS.
• `ALLOW` использует соединения без TLS, если база данных не требует HTTPS/TLS.
• `PREFER` использует HTTPS/TLS‑соединения, если база данных их предлагает.
• `REQUIRE` использует только HTTPS/TLS‑соединения.
• `VERIFY-CA` использует только HTTPS/TLS‑соединения и проверяет, что сертификат сервера является действительным и доверенным.
• `VERIFY-FULL` использует только HTTPS/TLS‑соединения, проверяет, что сертификат сервера является действительным и доверенным, а также что сертификат сервера соответствует hostname базы данных. | | `sslprotocol` | `"TLSv1.2"` | string | Указывает TLS‑протокол для HTTPS/TLS‑соединений. Эквивалентно параметру подключения `SSLPROTOCOL` драйвера Teradata JDBC. | | `teradata_values` | `"true"` | quoted boolean | Управляет тем, используется ли тип `str` или более специфичный тип данных Python для некоторых типов значений столбцов в наборе результатов. | | `query_band` | `"org=teradata-internal-telem;appname=dbt;"` | string | Указывает строку Query Band, которая будет устанавливаться для каждого SQL‑запроса. | Обратитесь к [параметрам подключения](https://github.com/Teradata/python-driver#connection-parameters) для полного описания параметров подключения. ## Поддерживаемые функции ### Материализации * `view` * `table` * `ephemeral` * `incremental` #### Инкрементальная материализация Поддерживаются следующие стратегии инкрементальной материализации: * `append` (по умолчанию) * `delete+insert` * `merge` * `valid_history` — режим (или параметр), который управляет тем, как dbt учитывает и сохраняет исторические версии данных. Обычно используется в контексте инкрементальных моделей или снапшотов, когда важно корректно отслеживать изменения во времени и работать с «исторической» версией записей. * `microbatch` — подход к обработке данных небольшими порциями (батчами). В dbt используется для более частого и мелкого обновления данных по сравнению с классическими батчами, что позволяет снизить задержку обновлений и эффективнее обрабатывать большие объёмы данных. к сведению * Чтобы узнать больше о стратегиях инкрементальной материализации в dbt, обратитесь к [документации по инкрементальной стратегии dbt](https://docs.getdbt.tech/docs/build/incremental-strategy.md). * Чтобы узнать больше о стратегии инкрементальной материализации `valid_history`, обратитесь к [конфигурациям Teradata](https://docs.getdbt.tech/reference/resource-configs/teradata-configs.md). ### Команды Все команды dbt поддерживаются. ## Поддержка контрактов моделей Контракты моделей поддерживаются с dbt-teradata версии 1.7.1 и выше. Поддержка и применение ограничений в dbt-teradata: | Тип ограничения | Поддержка Платформа | Применение | | --------------- | ------------------- | -------------- | | not\_null | ✅ Поддерживается | ✅ Применяется | | primary\_key | ✅ Поддерживается | ✅ Применяется | | foreign\_key | ✅ Поддерживается | ✅ Применяется | | unique | ✅ Поддерживается | ✅ Применяется | | check | ✅ Поддерживается | ✅ Применяется | Подробнее см. [Model contracts](https://docs.getdbt.tech/docs/mesh/govern/model-contracts.md). ## Поддержка пакета `dbt-utils` Пакет `dbt-utils` поддерживается через пакет dbt `teradata/teradata_utils`. Пакет предоставляет слой совместимости между `dbt_utils` и `dbt-teradata`. См. пакет [teradata\_utils](https://hub.getdbt.com/teradata/teradata_utils/latest/) для инструкций по установке. ### Кросс-базовые макросы Начиная с версии 1.3, некоторые макросы были перенесены из пакета dbt [teradata-dbt-utils](https://github.com/Teradata/dbt-teradata-utils) в коннектор. Обратитесь к следующей таблице для макросов, поддерживаемых коннектором. Для использования кросс-базовых макросов пространство имен макросов teradata-utils не будет использоваться, так как кросс-базовые макросы были перенесены из teradata-utils в Dbt-Teradata. #### Совместимость | Группа макросов | Название макроса | Статус | Комментарий | | --------------------- | ------------------ | ------ | ------------------------------------------------------------------------------ | | Кросс-базовые макросы | current\_timestamp | ✅ | предоставлен пользовательский макрос | | Кросс-базовые макросы | dateadd | ✅ | предоставлен пользовательский макрос | | Кросс-базовые макросы | datediff | ✅ | предоставлен пользовательский макрос, см. [заметку о совместимости](#datediff) | | Кросс-базовые макросы | split\_part | ✅ | предоставлен пользовательский макрос | | Кросс-базовые макросы | date\_trunc | ✅ | предоставлен пользовательский макрос | | Кросс-базовые макросы | hash | ✅ | предоставлен пользовательский макрос, см. [заметку о совместимости](#hash) | | Кросс-базовые макросы | replace | ✅ | предоставлен пользовательский макрос | | Кросс-базовые макросы | type\_string | ✅ | предоставлен пользовательский макрос | | Кросс-базовые макросы | last\_day | ✅ | не требуется настройка, см. [заметку о совместимости](#last_day) | | Кросс-базовые макросы | width\_bucket | ✅ | не требуется настройка | | Кросс-базовые макросы | generate\_series | ✅ | предоставлен пользовательский макрос | | Кросс-базовые макросы | date\_spine | ✅ | не требуется настройка | #### Примеры для кросс-базовых макросов ##### []()replace {{ dbt.replace("string\_text\_column", "old\_chars", "new\_chars") }} {{ replace('abcgef', 'g', 'd') }} ##### []()date\_trunc {{ dbt.date\_trunc("date\_part", "date") }} {{ dbt.date\_trunc("DD", "'2018-01-05 12:00:00'") }} ##### []()datediff Макрос `datediff` в teradata поддерживает вычисление разницы между датами. Вычисление разницы между временными метками не поддерживается. ##### []()hash Макрос `Hash` требует реализации функции `md5`. Teradata не поддерживает `md5` нативно. Вам необходимо установить пользовательскую функцию (User Defined Function, UDF) и при необходимости указать переменную `md5_udf` ([variable](https://docs.getdbt.tech/docs/build/project-variables.md)). Если переменная не указана, код по умолчанию использует `GLOBAL_FUNCTIONS.hash_md5`. Ниже приведены инструкции по установке пользовательской UDF: 1. Скачайте реализацию md5 UDF от Teradata (требуется регистрация): . 2. Распакуйте архив и перейдите в каталог `src`. 3. Запустите `bteq` и подключитесь к вашей базе данных. 4. Создайте базу данных `GLOBAL_FUNCTIONS`, в которой будет размещена UDF. Вы не можете изменить имя базы данных, так как оно жестко задано в макросе: ```sql CREATE DATABASE GLOBAL_FUNCTIONS AS PERMANENT = 60e6, SPOOL = 120e6; ``` 5. Создайте UDF. Замените `` на вашего текущего пользователя базы данных: ```sql GRANT CREATE FUNCTION ON GLOBAL_FUNCTIONS TO ; DATABASE GLOBAL_FUNCTIONS; .run file = hash_md5.btq ``` 6. Предоставьте разрешения на выполнение UDF с опцией предоставления. ```sql GRANT EXECUTE FUNCTION ON GLOBAL_FUNCTIONS TO PUBLIC WITH GRANT OPTION; ``` Инструкция о том, как добавить переменную md5\_udf в dbt\_project.yml для пользовательской хеш-функции: ```yaml vars: md5_udf: Custom_database_name.hash_method_function ``` ##### []()last\_day `last_day` в `teradata_utils`, в отличие от соответствующего макроса в `dbt_utils`, не поддерживает `quarter` в качестве части даты. dbt-teradata версии 1.8.0 и более поздние версии поддерживают модульные тесты, позволяя вам проверять SQL-модели и логику с небольшим набором статических входных данных перед переходом в производство. Эта функция улучшает разработку, ориентированную на тестирование, и повышает эффективность разработчика и надежность кода. Узнайте больше о модульных тестах dbt [здесь](https://docs.getdbt.tech/docs/build/unit-tests.md). ## Ограничения ### Аутентификация через браузер * При запуске задания dbt с параметром `logmech`, установленным в значение `"browser"`, начальная аутентификация открывает окно браузера, в котором необходимо ввести имя пользователя и пароль. * После завершения аутентификации это окно остаётся открытым, и вам нужно вручную переключиться обратно в консоль dbt. * Для каждого последующего подключения кратковременно открывается новая вкладка браузера с сообщением **"TERADATA BROWSER AUTHENTICATION COMPLETED"**, при этом существующая сессия используется повторно без дополнительного ввода данных. * Однако фокус остаётся на окне браузера, поэтому каждый раз требуется вручную возвращаться в консоль dbt. * Такое поведение является стандартной функциональностью драйвера `teradatasql` и на данный момент не может быть изменено. * Чтобы избежать истечения срока действия сессии и необходимости повторного ввода учётных данных, убедитесь, что окно браузера для аутентификации остаётся открытым до завершения выполнения задания. ### Режим транзакций В dbt-teradata теперь поддерживаются оба режима транзакций — **ANSI** и **TERA**. Поддержка режима TERA была добавлена в dbt-teradata версии 1.7.1 и на данный момент является первоначальной реализацией. Режим транзакции TERA Это начальная реализация режима транзакции TERA и она может не поддерживать некоторые случаи использования. Мы настоятельно рекомендуем проверять все записи или преобразования, используя этот режим, чтобы избежать неожиданных проблем или ошибок. ## Благодарности Адаптер был изначально создан [Дугом Битти](https://github.com/dbeatty10). Teradata взяла на себя адаптер в январе 2022 года. Мы благодарны Дугу за создание проекта и ускорение интеграции dbt + Teradata. ## Лицензия Адаптер распространяется под лицензией Apache-2.0. Ознакомьтесь с [условиями лицензии](https://github.com/dbt-labs/dbt/blob/main/LICENSE), чтобы узнать о таких аспектах, как создание производных работ и модель поддержки.