Интеграция dbt с YDB

Введение

dbt (data build tool) - инструмент для трансформации данных в аналитических хранилищах, предназначенный для организации процессов разработки моделей данных по аналогии с разработкой программного обеспечения. Он охватывает этап трансформации (T) в ETL-пайплайнах и позволяет структурировать логику преобразований - от сырых данных до витрин - с поддержкой тестирования, документирования и data lineage - сквозной прослеживаемости данных от источника до конечной модели.

Модели в dbt определяются единообразно - как SELECT-выражения, что упрощает их сопровождение и композицию. Инструмент обеспечивает их материализацию в хранилище данных, а также отслеживает зависимости между моделями, в том числе в процессе эволюции одних и тех же данных через стадии преобразований.

Для интеграции dbt с YDB используется коннектор dbt-ydb. Он обеспечивает подключение к YDB в качестве целевой платформы и поддерживает материализацию моделей в виде таблиц и представлений, работу с инкрементальными данными, загрузку тестовых датасетов (seeds), а также выполнение тестов и генерацию документации.

В этом разделе описаны возможности коннектора, а также шаги по его первоначальной настройке и запуску.

Важно

Коннектор dbt-ydb находится в стадии Preview и, в настоящий момент, не обеспечивает поддержку всех возможностей dbt. Ниже приводится список возможностей и ограничений.

Возможности

Модели и их материализация

Ключевое понятие dbt — модель данных. По своей сути, это SQL‑выражение, в котором могут быть использованы все источники данных внутри вашего хранилища, включая другие модели. Существуют разные подходы к физическому созданию модели (ее материализации) внутри YDB, которые поддерживает коннектор dbt-ydb:

  1. Представление (view) — сохраняется как представление YDB.

  2. Таблица (table) — сохраняется как таблица внутри YDB и пересоздаётся при каждом обновлении модели силами dbt.

    dbt-ydb коннектор поддерживает возможность определять следующие параметры таблицы через конфигурацию модели:

    Параметр Обязательность Значение по умолчанию Описание
    primary_key Да Первичный ключ таблицы
    store_type Нет row Тип таблицы. 'row' - для строковой таблицы и 'column' для колоночной таблицы
    auto_partitioning_by_size Нет Автоматическое партиционирование по размеру
    auto_partitioning_partition_size_mb Нет Порог размера партиции
    ttl Нет Правило Time-To-Live

    Пример модели, материализуемой как таблица на основе другой модели (связаны через ref).
    Заданы первичный ключ, TTL и автоматическое партиционирование по размеру.

    {{ config(
   primary_key='id, created_at',
   store_type='row',
   auto_partitioning_by_size='ENABLED',
   auto_partitioning_partition_size_mb=256,
   ttl='Interval("P30D") on created_at'
) }}

select
   id,
   name,
   created_at
from {{ ref('source_table') }}

  3. Инкрементальное представление (incremental model) — создаётся как таблица внутри YDB, но при обновлении не пересоздаётся, а обновляется изменившимися и новыми строками.

    dbt-ydb коннектор поддерживает те же параметры, что определены для табличной материализации, а также уникальные параметры инкрементального представления:

    Параметр Обязательность Значение по умолчанию Описание
    incremental_strategy Нет MERGE Стратегия инкрементальной материлазации. Поддерживается стратегия MERGE, использующая YDB операцию UPSERT. Поддержка стратегии APPEND находится в разработке

Примечание

Еще один тип материализации, эфемерное представление, в данный момент не поддерживается коннектором.

Снепшоты

Механизм снепшотов в данный момент не поддерживается dbt-ydb.

Тестовые/справочные данные, создаваемые из файлов CSV (сиды)

dbt-ydb коннектор поддерживает возможность dbt определять сиды для загрузки справочных и тестовых данных из CSV‑файлов в ваш проект и их использование в других моделях.

Тестирование данных

dbt-ydb поддерживает стандартные тесты данных dbt, а также специфичные тесты в рамках возможностей YQL.

Генерация документации

dbt-ydb поддерживает создание документации из проектов dbt для YDB.

Подготовка к использованию

Зависимости

Для начала работы с dbt на YDB вам понадобятся:

  • Python 3.10+;
  • dbt Core (1.8+);
  • Существующий кластер YDB, однонодовая инсталляция из быстрого старта будет достаточной.

Примечание

Внимание! dbt Fusion (2.0) в данный момент не поддерживается.

Установка

Для установки dbt-ydb выполните

pip install dbt-ydb

Подключение dbt к YDB кластеру

dbt подключается к YDB через dbt-ydb коннектор стандартным для YDB образом. Для успешного подключения требуется указать эндпоинт, путь к базе данных, а также параметры аутентификации в файле профилей dbt.

Пример файла профилей с возможными вариантами аутентификации, а также значениями по умолчанию (в квадратных скобках)

profile_name:
target: dev
outputs:
   dev:
      type: ydb
      host: [localhost] # YDB host
      port: [2136] # YDB port
      database: [/local] # YDB database
      schema: [<empty string>] # Optional subfolder for DBT models
      secure: [False] # If enabled, grpcs protocol will be used
      root_certificates_path: [<empty string>] # Optional path to root certificates file

      # Static Credentials
      username: [<empty string>]
      password: [<empty string>]

      # Access Token Credentials
      token: [<empty string>]

      # Service Account Credentials
      service_account_credentials_file: [<empty string>]

Создание проекта "c нуля" через команду dbt init

  1. Инициализация проекта

    dbt init

  2. Cледуйте интерактивным подсказкам dbt для выбора коннектора dbt-ydb и настроек аутентификации, подходящих для вашего кластера YDB

  3. В результате директория с вашим проектом, а также файл профилей dbt в домашней директории пользователя будет создан или обновлен новым соединением к YDB

    ~/.dbt/profiles.yml

  4. Запустите команду dbt debug для проверки соединения

    dbt debug

  5. Внутри директории вашего проекта, вы увидите следующую структуру

    dbt-ydb new project structure

  6. Адаптация модели my_first_dbt_model

    В данный момент dbt не поддерживает возможности модификации автоматически генерируемого примера индивидуально под коннектор, поэтому, для запуска данной модели через dbt-ydb требуется ее обновить следующим образом:

    /*
   Welcome to your first dbt model!
   Did you know that you can also configure models directly within SQL files?
   This will override configurations stated in dbt_project.yml

   Try changing "table" to "view" below
*/

{{ config(materialized='table', primary_key='id') }}

select *
from (
   select 1 as id
   union all
   select null as id
)

  7. Теперь вы можете запустить ваш проект

    dbt run

Запуск тестового примера

Вместе с коннектором dbt-ydb поставляется пример, который можно использовать для быстрой проверки возможностей dbt для YDB

  1. Клонирование репозитория

    git clone https://github.com/ydb-platform/dbt-ydb.git
cd dbt-ydb/examples/jaffle_shop

  2. Настройка файла профиля подключения к вашей YDB в файле profiles.yml. Для однонодовой инсталляции из быстрого старта файл будет выглядеть следующим образом

    profile_name:
   target: dev
   outputs:
  dev:
     type: ydb
     host: localhost # Хост YDB
     port: 2136 # Порт YDB
     database: /local # База данных YDB
     schema: jaffle_shop

  3. Проверьте подключение

    dbt debug

  4. Подготовьте тестовые данные через seeds

    Эта команда загрузит CSV-файлы из директории data/ в таблицы raw_* YDB.

    dbt seed

  5. Запустите выполнение моделей

    Будут созданы таблицы и представления на основе примеров моделей проекта.

    dbt run

  6. Протестируйте данные в моделях

    Данная команда выполнит стандартные проверки данных, описанные в тестовом примере — проверки на null, на допустимые значения списка и другие.

    dbt test

  7. Сгенерируйте документацию и запустите локальный веб-сервер для её просмотра

    Документация по проекту будет доступна в браузере: http://localhost:8080.

    dbt docs generate
dbt docs serve --port 8080

Дальнейшие шаги

Официальную документацию dbt можно найти по ссылке.
Дополнительно вы можете изучить исходный код коннектора, а также поучаствовать в его развитии в публичном репозитории dbt-ydb на GitHub.

Предыдущая
Миграции данных
Следующая
Flyway