Глоссарий — dbt I

Data Build Tool — open-source framework для трансформаций в data warehouse через SQL + Jinja templating. Центральный инструмент analytics engineering: вы пишете SELECT-запросы, а dbt компилирует их в DDL/DML, выстраивает DAG зависимостей и материализует результаты.

Роль на стыке data engineering и data analytics. Analytics engineer строит надёжные production-grade модели данных в warehouse, используя software-engineering практики (Git, тесты, code review). dbt — каноничный инструмент этой роли.

Extract -> Load -> Transform. Сырые данные сначала грузятся в warehouse (ELT-loader типа Fivetran/Airbyte), и только потом трансформируются внутри warehouse (dbt). Противоположность ETL: трансформация близко к данным, а не до загрузки.

Extract -> Transform -> Load. Классический подход: данные трансформируются на промежуточном compute-слое (Spark, Airflow tasks), затем результаты грузятся в DWH. Менее популярен сейчас, потому что warehouse-compute стал дешёвым и масштабируемым.

Аналитическая СУБД с column-oriented storage и SQL-интерфейсом. Snowflake, BigQuery, Redshift, Databricks SQL, DuckDB. Все трансформации dbt выполняются движком warehouse — dbt лишь генерирует SQL.

Python-плагин dbt, который умеет говорить с конкретным warehouse: dbt-snowflake, dbt-bigquery, dbt-postgres, dbt-duckdb. Содержит macros для DDL/DML диалекта и connection-логику. Устанавливается через pip.

CLI и core-библиотека dbt. Open-source, MIT. Запускается локально, в Docker или в CI через `dbt run`, `dbt test`, `dbt build`. Версия на 2026 — 1.10 (актуальный stable).

SaaS-обёртка вокруг dbt-core с веб-IDE (dbt Studio), job-scheduler'ом, мониторингом, lineage-explorer'ом, semantic layer'ом. Free Developer tier бесплатен для одного пользователя. DuckDB официально не поддерживается.

Rust-based next-gen engine для dbt, public beta с мая 2025, GA на Coalesce 2025. Параллельная парсилка, статический SQL-анализ через SDF, drop-in замена dbt-core. Junior должен знать что есть; учиться продолжаем на Core 1.10.

Запись в `~/.dbt/profiles.yml`, описывающая подключение к warehouse: тип адаптера, путь/хост, креды, threads. На один dbt-проект может быть несколько профилей, переключаемых через `--profile` или поле `profile:` в `dbt_project.yml`.

Именованный output внутри profile: dev, prod, ci. Выбирается через `--target` или дефолтный `target:` в profile. В моделях доступен через `{{ target.name }}`, `{{ target.schema }}` — типичный паттерн для dev/prod schema branching.

SQL-файл (`.sql`) в `models/`, содержащий SELECT-запрос. dbt компилирует его в `CREATE TABLE AS` / `CREATE VIEW AS` / INSERT в зависимости от materialization. Имя модели = имя файла без расширения.

Raw-таблица, загруженная в warehouse extract-loader'ом (Fivetran, Stitch). Декларируется в YAML под `sources:`, ссылается через `{{ source('schema', 'table') }}`. Sources — листья DAG, на них тоже можно вешать тесты и freshness-чеки.

CSV-файл в `seeds/`, который `dbt seed` грузит в warehouse как таблицу. Подходит для маленьких справочников (country_codes, product_catalog). Не для больших датасетов — git раздуется.

SCD Type 2 механизм dbt. Сохраняет историю изменений source-таблицы: каждая строка получает `dbt_valid_from` / `dbt_valid_to`. Конфигурируется через `unique_key` + стратегию `timestamp` или `check`. С 1.9 можно описывать в YAML, а не только в `.sql`.

Стратегия, как dbt превратит SELECT в объект warehouse: view, table, ephemeral, incremental, materialized_view. Конфигурируется через `{{ config(materialized='...') }}` в модели или в `dbt_project.yml`.

Materialization по умолчанию. dbt компилирует модель в `CREATE OR REPLACE VIEW`. Дешёвая запись, но каждый downstream-запрос пересчитывает её. Хорошо для тонких staging-моделей с минимумом логики.

Materialization `table` -> `CREATE TABLE AS SELECT`. Полный rebuild при каждом `dbt run`. Дороже view, но downstream-запросы быстрые. Дефолт для marts и для тяжёлых intermediate.

Materialization `ephemeral` — модель не материализуется как объект, а инлайнится в downstream как CTE. Нет физического объекта в warehouse. Удобно для маленьких переиспользуемых кусков SQL, но глубокая вложенность даёт монструозные CTE-деревья.

Materialization, при которой `dbt run` обновляет только новые/изменённые строки, не пересчитывая всю таблицу. Конфигурируется через `incremental_strategy` (append/merge/delete+insert/microbatch) + опциональный `unique_key`. Внутри модели проверка `{% if is_incremental() %}` фильтрует входящие данные.

Materialization для warehouse, поддерживающих native MV (Snowflake, BigQuery, Postgres). Warehouse сам инкрементально обновляет MV. В dbt-duckdb НЕ поддержано (DuckDB MV пока экспериментальные).

Jinja-функция в dbt-моделях для ссылки на другую модель: `{{ ref('stg_orders') }}`. Подставляет полный путь `database.schema.table` для текущего target и строит DAG зависимостей. Без `ref()` dbt не знает порядок выполнения и не построит lineage.

Jinja-функция для ссылки на source: `{{ source('jaffle_raw', 'orders') }}`. Подставляет full-qualified имя из секции `sources:` в YAML. Должна использоваться вместо хардкода имени raw-таблицы.

Directed Acyclic Graph — направленный граф моделей и их зависимостей, который dbt строит на основе `ref()` и `source()` вызовов. Используется для порядка выполнения, lineage-визуализации и node selection (`+model+`, `model+`, и т.д.).

Визуализация DAG в dbt docs: от какой source-таблицы какая marts-модель в итоге зависит. Критично для impact analysis (что сломается, если изменю эту source-колонку) и для аудита.

Финальный SQL, который dbt отправляет в warehouse после раскрытия Jinja-шаблонов (`ref`, `source`, `var`, macros). Лежит в `target/compiled/<project>/models/...sql`. Первое место, куда смотрит junior при дебаге.

`target/run/<project>/models/...sql` — compiled SQL, обёрнутый в DDL (CREATE TABLE AS / MERGE / etc) в зависимости от materialization. Это то, что фактически выполняется в warehouse.

Jinja-блок внутри модели для inline-конфига: `{{ config(materialized='table', tags=['daily'], unique_key='id') }}`. Эквивалент секции в `dbt_project.yml`, но per-model. Должен идти ДО SELECT, иначе игнорируется.

Корневой манифест проекта. Содержит name, version, profile, paths (`model-paths`, `seed-paths`, ...), глобальные `+materialized`, `+tags`, `+meta` per-folder, hooks. Должен лежать в корне проекта; `dbt run` ищет его в текущей директории и выше.

Файл с креденшалами и connection-параметрами. По умолчанию в `~/.dbt/profiles.yml`, можно переопределить через `--profiles-dir`. Никогда не должен попадать в git (используйте env_var()).

Манифест зависимостей dbt-проекта. Содержит список packages (hub, git, local) с версиями. `dbt deps` устанавливает их в `dbt_packages/`. Самый частый dependency — dbt-labs/dbt_utils.

Декларативный тест в YAML, проверяющий column-level invariant: `not_null`, `unique`, `accepted_values: [...]`, `relationships: {to: ref('...'), field: 'id'}`. Из коробки доступны 4; больше — через dbt_utils / dbt_expectations / самописные.

`.sql`-файл в `tests/`, содержащий SELECT. Тест проходит, если запрос вернул 0 строк. Используется для бизнес-инвариантов, не привязанных к одной колонке: `SELECT 1 FROM mart WHERE total_revenue < 0`.

С dbt 1.8+ — тесты на логику модели с фиксированными входами и ожидаемым выходом (`given:` / `expect:`). Запускаются БЕЗ обращения к warehouse-данным, через моки. Подходят для покрытия CASE-WHEN, оконных функций, сложных JOIN.

Переиспользуемый кусок Jinja-кода, объявленный через `{% macro name(arg) %}...{% endmacro %}` в `macros/`. Вызывается из моделей: `{{ my_macro('x') }}`. dbt сам — это набор макросов; диалект warehouse тоже реализован макросами в адаптере.

Python-шаблонизатор (jinja2), которым dbt дополняет SQL. Три синтаксиса: `{{ expression }}` — выражение, `{% statement %}` — control flow (set/for/if), `{# comment #}` — комментарий. Любой `.sql`-файл в dbt — это Jinja+SQL.

Произвольный SQL/Jinja, запускаемый dbt вокруг модели или run'а: `pre_hook`, `post_hook` на моделях; `on-run-start`, `on-run-end` на уровне проекта. Типичные применения: GRANT'ы, audit-log, vacuum/analyze.

Внешний dbt-проект, подключаемый через `packages.yml`. Содержит макросы, generic-тесты, иногда модели. Устанавливается в `dbt_packages/`. Self-contained — не зависит от структуры вашего проекта.

Канонический package от dbt Labs. Даёт мастхэв-макросы: `star()` (все колонки кроме списка), `pivot()`, `generate_surrogate_key()`, `union_relations()`, `equal_rowcount` тест, `accepted_range`. Ставится в 99% production-проектов.

Package, портирующий Great Expectations-подобные тесты в dbt: `expect_column_values_to_match_regex`, `expect_table_row_count_to_be_between` и десятки других. Используется для расширенных data-quality чеков.

YAML-декларация в `models/` о downstream-потребителе данных: dashboard, ML-модель, API, application. Не запускается, но появляется в dbt docs и в lineage. Полезно для impact analysis.

Логическая группировка моделей с владельцем (`owner: name / email`). Декларируется в YAML, ссылается через `config(group='...')`. Используется вместе с `access` для контроля видимости между группами.

Уровень видимости модели для других проектов в dbt Mesh: `private`, `protected`, `public`. `private` доступна только внутри группы; `public` — экспортируется через cross-project ref. На junior-уровне обычно не настраивается.

`target/manifest.json` — машинно-читаемое описание DAG, моделей, sources, tests, документации после парсинга. Используется dbt docs, state-comparison-флагами (`--defer`, `state:modified`) и внешними тулзами (dbt-osmosis, datafold).

`target/catalog.json`, генерируется `dbt docs generate`. Содержит метаданные warehouse-объектов: типы колонок, статистики, размеры. Заполняет panes в dbt docs.

`target/run_results.json` — результат последнего run'а: какие модели прошли, упали, сколько строк, время. Используется `--state` сравнениями и для retry-логики (`dbt retry`).

Jinja-функция, возвращающая True, если идёт incremental-run (модель существует в warehouse + не `--full-refresh`). Внутри `{% if is_incremental() %}` пишут WHERE updated_at > (SELECT max(...) FROM {{ this }}) — фильтр новых данных.

Конфиг для incremental и snapshot. Колонка (или список колонок), по которой dbt определяет, что строка уже есть и её надо обновить. Без него merge/delete+insert не знает, что апдейтить. NULL в unique_key даёт дубли.

Как именно dbt обновляет incremental-модель: `append` (просто INSERT), `delete+insert` (DELETE matching -> INSERT), `merge` (MERGE INTO, нужен warehouse-support), `microbatch` (per-batch DELETE+INSERT, dbt-core 1.9+). Выбор зависит от адаптера и нужд.

Колонка типа timestamp, по которой dbt разбивает incremental-microbatch на батчи. Конфигурируется в `config(event_time='created_at')`. Обязательна для microbatch стратегии.

Jinja-statement для объявления переменной внутри шаблона: `{% set columns = ['a', 'b'] %}`. Scope — текущий файл (либо block). Часто используется для генерации списка колонок перед for-loop.

Jinja-цикл: `{% for col in columns %} sum({{ col }}) as sum_{{ col }} {% if not loop.last %},{% endif %} {% endfor %}`. Главный инструмент генерации повторяющегося SQL (pivot, dynamic columns).

Jinja-условный statement: `{% if target.name == 'prod' %}...{% else %}...{% endif %}`. Типичное применение — переключать поведение модели между dev и prod (sample, partition limit).

Глобальная Jinja-переменная dbt. True во время run/test (execute-phase), False во время `dbt parse` (parse-phase). `run_query` возвращает результат только когда `execute=True` — иначе вернёт None, и манипуляции с ним упадут.

Jinja-функция dbt для синхронного запроса к warehouse прямо из шаблона: `{% set result = run_query('select distinct status from raw') %}`. Возвращает agate.Table. Использовать всегда внутри `{% if execute %}`.

Jinja-функция для вывода в stdout: `{{ log('compiling stg_orders', info=True) }}`. Главный debug-инструмент в макросах. С `info=True` показывается всегда; без — только при `--debug`.

Jinja-функция, читающая переменную из `dbt_project.yml` секции `vars:` или из CLI `--vars '{"k":"v"}'`. С дефолтом: `{{ var('start_date', '2024-01-01') }}`. Используется для параметризации dev-windows, sample-фильтров.

Jinja-функция для чтения OS environment variable: `{{ env_var('SNOWFLAKE_PASSWORD') }}`. Главный способ держать секреты вне git. С дефолтом: `{{ env_var('DBT_THREADS', '4') }}`.

Имя текущего target'а (dev/prod/ci). Используется в моделях для условной логики и в `generate_schema_name` для dev-suffix'а. Не путать с `target.schema` (целевая схема).

Built-in макрос dbt, решающий, в какую схему запишется модель. Дефолтная реализация: для dev — `<target.schema>_<custom_schema>`, для prod — `<custom_schema>` напрямую. Можно override'ить в `macros/get_custom_schema.sql`.

Аргумент `--select` (и/или `--exclude`) в dbt-командах. Можно указывать имя модели, граф-операторы (`+model+`, `1+model`, `@model`), методы (`tag:daily`, `path:marts/`, `state:modified`, `resource_type:test`), и комбинации через `space` (intersection) и `,` (union).

Сравнение текущего manifest.json с предыдущим (`--state path/`). Селекторы `state:modified`, `state:new` позволяют запускать только изменённые модели. Foundation для slim CI.

Флаг `--defer` (с `--state path/`): неизменённые upstream-модели не пересоздаются в dev — `ref()` подменяется на prod-таблицу из manifest'а state. Резко ускоряет dev-итерации.

CI-паттерн в dbt: `dbt build --select state:modified+ --defer --state prod_artifacts/`. Запускает только изменённые модели + их downstream, поднимая upstream из prod. Стандартный pipeline в dbt Cloud Jobs.

Явная декларация схемы модели в YAML под `config: {contract: {enforced: true}}`. Каждой колонке указывается `data_type` и опционально `constraints`. При нарушении dbt падает. Защищает downstream от случайного изменения схемы.

Возможность держать одновременно несколько версий одной модели (v1/v2) для постепенной миграции downstream. Декларируется через `versions:` в YAML. Чаще встречается в dbt Mesh / multi-team среде.

Паттерн архитектуры из нескольких dbt-проектов, ссылающихся друг на друга через cross-project `ref` + access=public. Поддерживается полноценно в dbt Cloud (с manifest sharing). Полезен для крупных орг-структур.

Веб-IDE в dbt Cloud (Free Developer tier). Браузерный VSCode-like редактор с git-интеграцией, preview, lineage, autocomplete. Заменил classic Cloud IDE.

Embedded analytical OLAP-database. Column-store, vectorized executor, Postgres-совместимый SQL диалект. Используется как warehouse для dbt-duckdb локально, без docker и серверов. Версия на 2026 — 1.1+.

Адаптер dbt для DuckDB. Версия 1.10.x работает с dbt-core 1.8-1.10 и DuckDB 1.1+. Поддерживает все базовые materializations, кроме materialized_view. Уникальные фичи: external materialization (Parquet), read_parquet прямо в модели.

DuckDB-specific materialization: `{{ config(materialized='external', location='s3://bucket/data.parquet') }}`. Пишет результат прямо в Parquet/CSV-файл вместо таблицы. Используется для data lake архитектур.

DuckDB extension `httpfs`, позволяющая читать данные напрямую из S3/HTTP в SELECT: `SELECT * FROM read_parquet('s3://bucket/file.parquet')`. Подключается в profiles.yml через `extensions: [httpfs]`.

Дефолтная схема в profiles.yml: `schema: main` (для DuckDB обычно). В неё пишутся модели, если в `dbt_project.yml` или `config()` не указан custom schema.

Параметр profile, определяющий, сколько моделей dbt параллельно запускает в warehouse. Для DuckDB обычно 4–8. Не путать с DuckDB-internal threading (тоже параметризуется в settings).

CLI-команда: запускает все модели в порядке DAG. Опции: `--select`, `--exclude`, `--full-refresh`, `--target`, `--vars`. Сеялки и тесты НЕ запускает — для всего комбо используйте `dbt build`.

Запускает generic + singular тесты. По умолчанию параллельно через threads. Можно фильтровать селектором: `dbt test --select stg_orders` запустит тесты на модели stg_orders.

Композитная команда: для каждой ноды выполняет run -> test в правильном порядке. Если тест на upstream-модель упал — downstream не запускаются (`skipped`). Рекомендуемая команда в CI.

Парсит проект и пишет compiled SQL в `target/compiled/`, без выполнения в warehouse. Используется для проверки Jinja и для debug compiled запроса.

Проверка соединения: читает profiles.yml, пытается подключиться к warehouse, выводит OK/FAIL. Первое, что запускают при подозрении на проблемы с конфигом или сетью.

Устанавливает packages из `packages.yml` в `dbt_packages/`. Запускать после клонирования репо и после каждого изменения packages.yml. Без этого `dbt run` не найдёт макросы из пакетов.

Грузит все CSV из `seeds/` в warehouse как таблицы. Имя таблицы = имя файла. Поддерживает `column_types`, `quote_columns` в YAML. Не подходит для больших файлов — git замедлится.

Выполняет все snapshot'ы — фиксирует текущее состояние source-таблиц с SCD2 семантикой. Обычно запускается отдельно от run'а, чаще (раз в час), чтобы не пропустить промежуточные апдейты.

Подкоманда `dbt docs generate` пишет catalog.json + manifest.json, а `dbt docs serve` поднимает локальный сервер на 8080 с интерактивным DAG, descriptions, схемами. В CI часто публикуют статикой на S3/GitHub Pages.

Удаляет `target/` и `dbt_packages/`. Полезно при странном кэше или конфликте версий пакетов: `dbt clean && dbt deps`.

Запускает SELECT модели/source и печатает первые N строк (по умолчанию 5) в stdout. Альтернатива `LIMIT 5` в SQL-клиенте, не оставляет следов в warehouse. Удобно для быстрой проверки результата.

Печатает список нод, удовлетворяющих селектору, без выполнения. `dbt list --select state:modified+` — посмотреть, что попадёт в slim CI.

Запускает произвольный макрос вне модели: `dbt run-operation grant_select --args '{role: analyst}'`. Используется для ad-hoc maintenance: GRANT'ы, очистка staging, backfill.

Тонкий первый слой моделей: один-к-одному к source, renaming + casting + light deduplication. Имя — `stg_<source>__<table>`. Не делает JOIN'ов; они идут в intermediate/marts.

Промежуточный слой между staging и marts. Содержит сложную бизнес-логику, JOIN'ы, агрегации, prep-шаги перед итоговой витриной. Имя — `int_<purpose>`. Часто ephemeral, если используется только одной marts.

Витрина — финальная модель, которую читают аналитики и BI: dimension (dim_customers), fact (fct_orders), wide-tables. Имя без префикса или `<entity>`. Обычно materialized=table.

Упрощённая интерпретация подхода Kimball: fact-таблицы для событий, dimension-таблицы для сущностей, без формального star/snowflake. dbt-сообщество в `marts/` обычно идёт по Kimball-light, не по полному Inmon.

Искусственный первичный ключ модели, сгенерированный из натуральных полей: `{{ dbt_utils.generate_surrogate_key(['order_id', 'line_number']) }}`. Хэш-сумма, стабильная между run'ами.

Кусок markdown-документации, объявленный через `{% docs name %}...{% enddocs %}` в `.md`-файле. Ссылается из YAML: `description: '{{ doc("name") }}'`. Позволяет переиспользовать длинные описания между моделями.

Проверка возраста данных в source через `dbt source freshness`. Конфигурируется в YAML: `loaded_at_field` + `warn_after / error_after` интервалы. Помогает поймать остановленный extract-loader.

Колонка source-таблицы с timestamp последнего апдейта (`updated_at`, `_loaded_at`, `etl_timestamp`). dbt берёт MAX от неё и сравнивает с `current_timestamp` для freshness-чека.

В DuckDB и Postgres identifiers case-insensitive, но dbt по умолчанию quoting=false для DuckDB. Если в source-таблице колонки `"OrderID"`, нужно `quoting: column: true` в YAML — иначе dbt всё нижне-регистрит.

Strategy для snapshot'а: `strategy=timestamp, updated_at='updated_at'`. dbt сравнивает updated_at между snapshot'ом и source — если отличается, закрывает старую и открывает новую версию строки.

Strategy `check`: dbt сравнивает значения указанных колонок (`check_cols=['name', 'email']` или `'all'`). Если хоть одна изменилась — создаёт новую версию. Дороже timestamp, нужен когда updated_at нет/ненадёжен.

Стандартный .gitignore dbt-проекта исключает: `target/`, `dbt_packages/`, `logs/`, `.user.yml`. Plus DuckDB-specific: `*.duckdb`, `*.duckdb.wal`. profiles.yml в корне проекта тоже надо игнорировать, если хранится там.

С dbt 1.10 поддержаны YAML anchors (`&name`) и aliases (`*name`) в моделях/sources/snapshots. Позволяют DRY config-блоки в больших YAML-файлах. До 1.10 надо было дублировать.