Пошаговый туториал по dbt (Data Build Tool) с примерами и готовыми командами: инициализация проекта, модели, тесты и документация. Время выполнения: базовый проход 20–45 минут, настройка CI и интеграции — 1–2 часа.
0
Статья была полезной?
Комментарии (0)
Войдите или зарегистрируйтесь, чтобы оставить комментарий
Загрузка комментариев…
Вы получите рабочий dbt-проект, пример модели на PostgreSQL, набор тестов и документацию доступную локально на порту 8080. Ожидаемое время полного прохождения туториала — 30–90 минут в зависимости от окружения.
Что вы изучите
Инициализация dbt-core 1.9.0 (релиз 15 января 2026) и подключение к PostgreSQL 15.
Создание моделей с использованием Jinja и функции ref(), пример incremental-модели.
Настройка unit-тестов (unique, not_null), генерация и локальный просмотр документации на порту 8080.
Простейшая интеграция в CI на примере GitHub Actions с кэшированием pip и безопасными секретами.
Практические советы по типичным ошибкам, их диагностике и исправлению.
Требования
ОС: Ubuntu 22.04 LTS или macOS 13 Ventura, Windows Subsystem for Linux (WSL2) допустим.
PostgreSQL 15 (порт по умолчанию 5432) доступен; минимальная схема для тестов: база данных analytics, схема analytics_dev.
Ресурсы: минимум 4 ГБ RAM, 2 CPU, 2 GB свободного места на диске. Docker optional; образ dbt: ~420–600 MB в зависимости от базового Python-образа.
Что такое dbt?
dbt (Data Build Tool) — инструмент для трансформаций данных, ориентированный на аналитиков и командную разработку SQL-логики. dbt позволяет описывать трансформации как версиированный код, автоматически строит DAG зависимостей через ref(), использует Jinja-шаблоны для параметризации SQL и обеспечивает встроенные тесты и документацию. dbt-core 1.9.0 (январь 2026) добавляет улучшения в инкрементальные модели и ускоренную генерацию manifest-файлов. Документация генерируется локально и обычно доступна через порт 8080.
Скриншот страницы dbt docs с графом зависимостей моделей
dbt делит ответственность: вы продолжаете загружать сырьевые данные в хранилище (PostgreSQL, Snowflake, BigQuery и т.д.), а dbt управляет преобразованиями поверх хранилища. Для чтения дополнительных статей по теме см. разделы Data Engineering и DevOps на сайте.
Шаг 1: инициализация
Команды ниже устанавливают dbt и создают шаблон проекта. Работает на Ubuntu 22.04 и macOS 13. Время выполнения: установка pip 1–2 минуты, создание проекта — мгновенно.
# Установка dbt-core и адаптера для PostgreSQL
python3 -m pip install --upgrade pip
python3 -m pip install dbt-core==1.9.0 dbt-postgres==1.9.0
Пояснение: установка ставит dbt-core и плагин для работы с PostgreSQL. Конкретная версия 1.9.0 указывает на релиз 15 января 2026; если нужен другой адаптер (BigQuery, Snowflake) замените пакет.
Типичная ошибка:
ERROR: Could not find a version that satisfies the requirement dbt-core==1.9.0
ERROR: No matching distribution found for dbt-core==1.9.0
Фикс: убедитесь, что используете Python 3.11 и pip обновлён. Проверьте совместимость платформы (ARM vs x86); на M1/M2 используйте соответствующий wheel или установку через Docker.
# Инициализация проекта в каталоге my_analytics
mkdir my_analytics && cd my_analytics
dbt init my_analytics_project --adapter postgres
Пояснение: команда создаст структуру каталогов (models/, profiles.yml пример и т.д.).
Ожидаемый вывод (успех):
Creating dbt_project.yml
Creating models/example.sql
Your new dbt project "my_analytics_project" has been created.
Типичная ошибка:
bash: dbt: command not found
Фикс: проверьте, что Python устанавливал пакеты в PATH. Выполните: python3 -m pip show dbt-core
Если установлен в виртуальном окружении — активируйте его: source venv/bin/activate
Скриншот терминала с выводом dbt init
Шаг 2: модели
Создадим простую модель и запустим её. Требуется корректно настроенный файл profiles.yml в ~/.dbt/profiles.yml или использовать переменные окружения для подключения.
# Пример profiles.yml в ~/.dbt/profiles.yml
my_analytics_profile:
target: dev
outputs:
dev:
type: postgres
host: localhost
user: analytics_user
password: secret_password
port: 5432
dbname: analytics
schema: analytics_dev
threads: 4
Пояснение: поле threads указывает число параллельных потоков (CPU). Минимум 2 потока рекомендуется для локальной разработки на 2 CPU.
# Создаём файл models/stg_customers.sql
-- models/stg_customers.sql
select
id,
lower(email) as email,
created_at::date as created_date
from raw.customers;
# Запуск моделей
dbt run --profiles-dir ~/.dbt
Ожидаемый вывод (успех):
Running with dbt=1.9.0
Found 1 model, 0 tests, 0 snapshots, 0 analyses, 0 macros
10:00:00 1 of 1 START view model my_analytics_project.stg_customers ................ [RUN]
10:00:01 1 of 1 OK created view model my_analytics_project.stg_customers ........ [OK in 1.20s]
Completed successfully
Типичная ошибка:
Database error: FATAL: database "analytics" does not exist
Фикс: создайте базу данных и нужную схему в PostgreSQL: psql -U postgres -c "CREATE DATABASE analytics;"; затем создайте схему analytics_dev или настройте schema в profiles.yml.
Ещё одна частая ошибка — синтаксическая ошибка Jinja/SQL. Пример: забытый <% %> или неправильный ref().
Ошибка компиляции:
Compilation Error in model stg_customers (models/stg_customers.sql)
'ref' is undefined
Фикс: убедитесь, что файл находится в каталоге models/ и dbt корректно ссылается; используйте {{ ref('model_name') }} внутри SQL. Проверьте синтаксис Jinja.
Шаг 3: tests и docs
Добавим тесты и сгенерируем документацию. Тесты выполняются быстро; типичный цикл тестирования для 10 моделей — 20–60 секунд локально.
# Добавьте файл models/schema.yml рядом с моделями
version: 2
models:
- name: stg_customers
description: "Staging customers, normalized emails and dates"
columns:
- name: id
tests: [not_null, unique]
- name: email
tests: [not_null]
Запуск тестов:
dbt test --profiles-dir ~/.dbt
Ожидаемый вывод (успех):
Found 1 model, 2 tests
10:05:00 1 of 2 START test not_null_my_analytics_project_stg_customers_id ... [RUN]
10:05:01 1 of 2 PASS not_null_my_analytics_project_stg_customers_id ...... [PASS in 0.70s]
10:05:02 2 of 2 PASS unique_my_analytics_project_stg_customers_id ........ [PASS in 0.30s]
All tests passed
Типичная ошибка:
FAIL not_null_my_analytics_project_stg_customers_email
Фикс: выполните диагностику в исходной таблице raw.customers: SELECT count(*) FROM raw.customers WHERE email IS NULL; исправьте данные или добавьте обработку null в модели.
Generating catalogs and manifest
Serving docs at: http://localhost:8080
Press CTRL+C to exit
Типичная ошибка:
Error: Port 8080 is already in use
Фикс: укажите другой порт: dbt docs serve --port 8081 или остановите процесс, который использует порт 8080 (например, lsof -i :8080).
Чем лучше чистого SQL?
dbt предоставляет набор преимуществ по сравнению с организацией трансформаций в чистых SQL-скриптах. Первое — явная зависимость между моделями через ref(), что делает DAG очевидным и позволяет пересобирать только необходимые узлы. Второе — встроенные тесты и документация, которые интегрируются в процесс разработки и CI. Третье — макросы и Jinja-параметры, позволяющие писать переиспользуемые фрагменты и избегать копипаста. Четвёртое — материализации (view, table, incremental), позволяющие оптимизировать производительность и уменьшающие нагрузку на хранилище.
# Пример инкрементальной модели с контролем изменения
-- models/incremental_sales.sql
{{ config(materialized='incremental', unique_key='sale_id') }}
select
sale_id,
amount,
sold_at
from raw.sales
where sold_at > (select max(sold_at) from {{ this }}) or {{ is_incremental() }} = false
Этот фрагмент показывает логику, которая в чистом SQL без фреймворка требует ручного управления состоянием. dbt упрощает поддержку и внедрение best practices, таких как тесты на уникальность и null-значения, а также управление версиями моделей через git. Кроме того, dbt поддерживает пакеты — общий код, которым можно делиться между проектами.
Как интегрировать в CI?
Ниже — пример GitHub Actions workflow, который выполняет установку, кэширование pip, запуск dbt run и dbt test. Рабочий процесс рассчитан на self-hosted или GitHub-hosted runner с минимум 4 ГБ RAM и 2 CPU. Ожидаемое время выполнения для средней пачки моделей (до 50 моделей) — 2–10 минут; для >200 моделей — 10–40 минут.
Комментарии (0)
Войдите или зарегистрируйтесь, чтобы оставить комментарий
Загрузка комментариев…