Пошаговый туториал по dbt (Data Build Tool) с примерами и готовыми командами: инициализация проекта, модели, тесты и документация. Время выполнения: базовый проход 20–45 минут, настройка CI и интеграции — 1–2 часа.
Статья была полезной?
Вы получите рабочий dbt-проект, пример модели на PostgreSQL, набор тестов и документацию доступную локально на порту 8080. Ожидаемое время полного прохождения туториала — 30–90 минут в зависимости от окружения.
ref(), пример incremental-модели.dbt-postgres 1.9.0.analytics, схема analytics_dev.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 на сайте.
Команды ниже устанавливают 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) замените пакет.
Ожидаемый вывод (успех):
Collecting dbt-core==1.9.0
Collecting dbt-postgres==1.9.0
... (зависимости)
Successfully installed dbt-core-1.9.0 dbt-postgres-1.9.0 ...Типичная ошибка:
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
Создадим простую модель и запустим её. Требуется корректно настроенный файл 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.Добавим тесты и сгенерируем документацию. Тесты выполняются быстро; типичный цикл тестирования для 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 в модели.Генерация и просмотр документации:
dbt docs generate --profiles-dir ~/.dbt
dbt docs serve --port 8080 --profiles-dir ~/.dbtОжидаемый вывод:
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).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 поддерживает пакеты — общий код, которым можно делиться между проектами.
Ниже — пример GitHub Actions workflow, который выполняет установку, кэширование pip, запуск dbt run и dbt test. Рабочий процесс рассчитан на self-hosted или GitHub-hosted runner с минимум 4 ГБ RAM и 2 CPU. Ожидаемое время выполнения для средней пачки моделей (до 50 моделей) — 2–10 минут; для >200 моделей — 10–40 минут.
# .github/workflows/dbt-ci.yml
name: dbt CI
on: [push, pull_request]
jobs:
dbt:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Cache pip
uses: actions/cache@v4
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install dbt-core==1.9.0 dbt-postgres==1.9.0
- name: Setup profiles
env:
DB_HOST: ${{ secrets.DB_HOST }}
DB_USER: ${{ secrets.DB_USER }}
DB_PASS: ${{ secrets.DB_PASS }}
DB_NAME: ${{ secrets.DB_NAME }}
DB_SCHEMA: ${{ secrets.DB_SCHEMA }}
run: |
mkdir -p ~/.dbt
cat > ~/.dbt/profiles.yml <
Комментарии (0)
Войдите или зарегистрируйтесь, чтобы оставить комментарий
Загрузка комментариев…