Подключение Teradata к dbt v1
Некоторые базовые функции могут быть ограничены. Если вы хотите внести свой вклад в разработку, ознакомьтесь с исходным кодом в репозитории, указанном в следующем разделе.
profiles.yml нужен только для dbt v1 и dbt v2Если вы используете dbt platform, создавать файл profiles.yml не нужно. Этот файл необходим только при локальном использовании v1 или v2. Подробнее о предварительных требованиях для v2 см. в разделе Поддерживаемые возможности. Чтобы подключить вашу платформу данных к dbt, см. раздел О платформах данных.
- Поддерживается: Teradata
- Авторы: Teradata
- Репозиторий GitHub: Teradata/dbt-teradata
- Пакет PyPI:
dbt-teradata
- Канал Slack: #db-teradata
- Поддерживаемая версия dbt: v0.21.0 и новее
- Поддержка dbt: Supported
- Минимальная версия платформы данных: n/a
Установка dbt-teradata
Установите адаптер с помощью `pip`:python -m pip install dbt-teradata
Настройка dbt-teradata
Конфигурацию, специфичную для Teradata, см. на странице настроек Teradata.
Совместимость с 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, необходимо добавить профиль в файл profiles.yml. Профиль Teradata имеет следующий синтаксис:
<profile-name>:
target: <target-name>
outputs:
<target-name>:
type: teradata
user: <username>
password: <password>
schema: <database-name>
tmode: ANSI
threads: [optional, 1 or more]
#optional fields
<field-name: <field-value>
Описание полей профиля 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‑запроса. |
Обратитесь к параметрам подключения для полного описания параметров подключения.
Поддерживаемые функции
Материализации
viewtableephemeralincremental
Инкрементальная материализация
Поддерживаются следующие стратегии инкрементальной материализации:
-
append(по умолчанию) -
delete+insert -
merge -
valid_history— режим (или параметр), который управляет тем, как dbt учитывает и сохраняет исторические версии данных. Обычно используется в контексте инкрементальных моделей или снапшотов, когда важно корректно отслеживать изменения во времени и работать с «исторической» версией записей. -
microbatch— подход к обработке данных небольшими порциями (батчами). В dbt используется для более частого и мелкого обновления данных по сравнению с классическими батчами, что позволяет снизить задержку обновлений и эффективнее обрабатывать большие объёмы данных.
- Чтобы узнать больше о стратегиях инкрементальной материализации в dbt, обратитесь к документации по инкрементальной стратегии dbt.
- Чтобы узнать больше о стратегии инкрементальной материализации
valid_history, обратитесь к конфигурациям Teradata.
Команды
Все команды dbt поддерживаются.
Поддержка контрактов моделей
Контракты моделей поддерживаются с dbt-teradata версии 1.7.1 и выше. Поддержка и применение ограничений в dbt-teradata:
| Тип ограничения | Поддержка Платформа | Применение |
|---|---|---|
| not_null | ✅ Поддерживается | ✅ Применяется |
| primary_key | ✅ Поддерживается | ✅ Применяется |
| foreign_key | ✅ Поддерживается | ✅ Применяется |
| unique | ✅ Поддерживается | ✅ Применяется |
| check | ✅ Поддерживается | ✅ Применяется |
Подробнее см. Model contracts.
Поддержка пакета dbt-utils
Пакет dbt-utils поддерживается через пакет dbt teradata/teradata_utils. Пакет предоставляет слой совместимости между dbt_utils и dbt-teradata. См. пакет teradata_utils для инструкций по установке.
Кросс-базовые макросы
Начиная с версии 1.3, некоторые макросы были перенесены из пакета dbt teradata-dbt-utils в коннектор. Обратитесь к следующей таблице для макросов, поддерживаемых коннектором.
Для использования кросс-базовых макросов пространство имен макросов teradata-utils не будет использоваться, так как кросс-базовые макросы были перенесены из teradata-utils в Dbt-Teradata.
Совместимость
| Группа макросов | Название макроса | Статус | Комментарий |
|---|---|---|---|
| Кросс-базовые макросы | current_timestamp | ✅ | предоставлен пользовательский макрос |
| Кросс-базовые макросы | dateadd | ✅ | предоставлен пользовательский макрос |
| Кросс-базовые макросы | datediff | ✅ | предоставлен пользовательский макрос, см. заметку о совместимости |
| Кросс-базовые макросы | split_part | ✅ | предоставлен пользовательский макрос |
| Кросс-базовые макросы | date_trunc | ✅ | предоставлен пользовательский макрос |
| Кросс-базовые макросы | hash | ✅ | предоставлен пользовательский макрос, см. заметку о совместимости |
| Кросс-базовые макросы | replace | ✅ | предоставлен пользовательский макрос |
| Кросс-базовые макросы | type_string | ✅ | предоставлен пользовательский макрос |
| Кросс-базовые макросы | 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).
Если переменная не указана, код по умолчанию использует GLOBAL_FUNCTIONS.hash_md5. Ниже приведены инструкции по установке пользовательской UDF:
- Скачайте реализацию md5 UDF от Teradata (требуется регистрация): https://downloads.teradata.com/download/extensibility/md5-message-digest-udf.
- Распакуйте архив и перейдите в каталог
src. - Запустите
bteqи подключитесь к вашей базе данных. - Создайте базу данных
GLOBAL_FUNCTIONS, в которой будет размещена UDF. Вы не можете изменить имя базы данных, так как оно жестко задано в макросе:CREATE DATABASE GLOBAL_FUNCTIONS AS PERMANENT = 60e6, SPOOL = 120e6; - Создайте UDF. Замените
<CURRENT_USER>на вашего текущего пользователя базы данных:GRANT CREATE FUNCTION ON GLOBAL_FUNCTIONS TO <CURRENT_USER>;
DATABASE GLOBAL_FUNCTIONS;
.run file = hash_md5.btq - Предоставьте разрешения на выполнение UDF с опцией предоставления.
GRANT EXECUTE FUNCTION ON GLOBAL_FUNCTIONS TO PUBLIC WITH GRANT OPTION;
Инструкция о том, как добавить переменную md5_udf в dbt_project.yml для пользовательской хеш-функции:
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 здесь.
Ограничения
Аутентификация через браузер
- При запуске задания dbt с параметром
logmech, установленным в значение"browser", начальная аутентификация открывает окно браузера, в котором необходимо ввести имя пользователя и пароль. - После завершения аутентификации это окно остаётся открытым, и вам нужно вручную переключиться обратно в консоль dbt.
- Для каждого последующего подключения кратковременно открывается новая вкладка браузера с сообщением "TERADATA BROWSER AUTHENTICATION COMPLETED", при этом существующая сессия используется повторно без дополнительного ввода данных.
- Однако фокус остаётся на окне браузера, поэтому каждый раз требуется вручную возвращаться в консоль dbt.
- Такое поведение является стандартной функциональностью драйвера
teradatasqlи на данный момент не может быть изменено. - Чтобы избежать истечения срока действия сессии и необходимости повторного ввода учётных данных, убедитесь, что окно браузера для аутентификации остаётся открытым до завершения выполнения задания.
Режим транзакций
В dbt-teradata теперь поддерживаются оба режима транзакций — ANSI и TERA. Поддержка режима TERA была добавлена в dbt-teradata версии 1.7.1 и на данный момент является первоначальной реализацией.
Это начальная реализация режима транзакции TERA и она может не поддерживать некоторые случаи использования. Мы настоятельно рекомендуем проверять все записи или преобразования, используя этот режим, чтобы избежать неожиданных проблем или ошибок.
Благодарности
Адаптер был изначально создан Дугом Битти. Teradata взяла на себя адаптер в январе 2022 года. Мы благодарны Дугу за создание проекта и ускорение интеграции dbt + Teradata.
Лицензия
Адаптер распространяется под лицензией Apache-2.0. Ознакомьтесь с условиями лицензии, чтобы узнать о таких аспектах, как создание производных работ и модель поддержки.
