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

Паттерн CI/CD в dbt, при котором собираются только изменённые модели и их downstream через `dbt build --select state:modified+ --defer --state ./prod-state`. Существенно сокращает время и стоимость CI runs на больших проектах. Требует свежего prod manifest.json в качестве baseline.

Селектор узлов, изменённых относительно baseline manifest (prod state). Плюс в конце включает всё downstream — иначе CI пропустит сломанные зависимости. Варианты: `state:modified` (только сами модели), `+state:modified+` (вверх и вниз). Используется парой с `--state ./prod-state`.

Флаг `--defer` указывает dbt брать `ref()` на не-modified upstream-модели из baseline-state (prod-схемы), а не пересобирать их в dev/CI. Без defer Slim CI потребует строить весь upstream. Часто пара с `state:modified+`.

Артефакт dbt после parse/compile. JSON с полным графом нод (models, tests, seeds, sources), их config, depends_on, file_path, raw_code, compiled_code, checksum. Используется как baseline для `state:modified` и для downstream-tooling (Explorer, Mesh, lineage).

Артефакт после `dbt run/test/build`. Содержит для каждой ноды: status (success/error/skipped), execution_time, rows_affected, message. Используется в `dbt retry`, для CI-репортов и метрик деплоев.

Артефакт после `dbt docs generate`. Метаданные warehouse: реальные колонки, типы, статистика, размеры таблиц. Объединяется с manifest для генерации lineage docs.

Объединённая команда `dbt run` + `dbt test` + `dbt seed` + `dbt snapshot` в правильном DAG-порядке: модель сначала строится, потом тестируется до того, как downstream начнёт строиться. Если тест fail — downstream skip'ается. Канон для CI.

Перезапуск только тех нод, что упали в предыдущем run, на основе `run_results.json`. Незаменимо для длинных prod-job'ов с transient errors (warehouse-таймауты). Сохраняет успешно прошедшие модели.

Стратегия инкрементальной материализации: `append`, `delete+insert`, `merge`, `insert_overwrite`, `microbatch`. Выбор зависит от warehouse, наличия unique_key и характера данных (immutable events vs mutable rows).

Простейшая incremental-стратегия: INSERT новых строк без проверки уникальности. Подходит для immutable append-only данных (events, logs). Дёшево, но без защиты от дублей при ретраях.

Incremental-стратегия: DELETE строк по unique_key где они matching, затем INSERT новой партии. Требует unique_key. Не-уникальный ключ -> many-to-many DELETE -> утрата данных и дубли. Дефолт для многих warehouses до появления merge.

Native MERGE INTO incremental-стратегия. UPDATE matching + INSERT non-matching в одном statement. На Snowflake/BigQuery/Databricks — production-default. DuckDB: MERGE поддерживается с 1.4+. Требует unique_key.

Incremental-стратегия для partitioned warehouses (BigQuery, Databricks SQL). Удаляет и пересоздаёт целые партиции из набора `partitions_to_replace` или вычисляется автоматически из incoming data. Идемпотентна, безопасна для backfill.

Incremental-стратегия из dbt-core 1.9+. Модель строится по батчам времени (`batch_size: hour/day/month`), каждый батч — отдельный DELETE+INSERT. Поддерживает параллельные батчи, retry, lookback и backfill через `--event-time-start/--event-time-end`. По дизайну без unique_key.

Имя колонки с временной меткой события. Обязательно для microbatch incremental. Используется dbt для определения границ батча: `WHERE event_time >= batch_start AND event_time < batch_end`. Должно быть UTC и monotonic.

Размер батча для microbatch: `hour`, `day` (default), `month`, `year`. Влияет на количество DELETE+INSERT statements и granularity backfill. Меньше -> больше queries, выше параллелизм; больше -> меньше overhead.

Сколько прошлых батчей включить в текущий microbatch run для обработки late-arriving data. Дефолт 1: пересчитывается предыдущий батч + текущий. Увеличивайте до 3-7 для систем с задержанными events.

Стартовая дата microbatch-модели. На первом run модель строится от `begin` до now, разбиваясь на батчи по `batch_size`. Влияет на full-refresh и backfill bounds.

Конфиг microbatch: `true` -> батчи строятся параллельно (быстрее, но требует idempotency и отсутствия порядковых зависимостей), `false` (default) -> последовательно. Race conditions при concurrent_batches на не-idempotent моделях.

Список дополнительных WHERE-условий, которые dbt добавит к MERGE / DELETE+INSERT для ограничения сканирования target-таблицы. Без `DBT_INTERNAL_DEST.` префикса они не помогут — dbt тихо сделает full scan. Критично на больших фактах.

Список колонок, которые обновляются при MATCHED в MERGE-стратегии. Если опущен, обновляются все. Используется когда нужно сохранить часть колонок неизменными (например, created_at).

Список колонок, исключённых из UPDATE в MERGE. Зеркало `merge_update_columns`. Удобно когда колонок много и проще перечислить исключения.

Конфиг incremental-модели: одна колонка или список колонок для match при delete+insert / merge. Должен быть реально уникальным после применения incremental WHERE — иначе many-to-many DELETE -> утрата данных. Microbatch — без unique_key.

Jinja-макрос, возвращающий true когда: (1) target-таблица уже существует, (2) run не `--full-refresh`. Обёртка для `{% if is_incremental() %} WHERE ... {% endif %}` чтобы фильтровать только новые строки на инкрементальных запусках.

Флаг `dbt run/build --full-refresh` — пересоздаёт incremental-модели с нуля как table (DROP + CREATE). Используется при изменении схемы или для регенерации. На очень больших фактах дорого. Защита: `config(full_refresh=false)` блокирует full-refresh.

Конфиг модели, запрещающий `--full-refresh`. Защита для microbatch / huge tables — где full-refresh = многочасовой запрос с риском уронить warehouse. Обходится через `--full-refresh` + explicit selector.

Slowly Changing Dimension type 2 — версионирование строк во времени. На каждое изменение создаётся новая строка с `dbt_valid_from`/`dbt_valid_to`, прошлая закрывается. Каноничный паттерн для аудита и time-travel queries по dimension-таблицам.

Materialization dbt для SCD2: команда `dbt snapshot` сравнивает source с предыдущим snapshot и фиксирует изменения через addition новых rows + закрытие старых через `dbt_valid_to`. Не пересоздаётся, только инкрементально дополняется. Состояние = вся история.

Snapshot strategy: dbt сравнивает `updated_at` колонку source с `dbt_valid_to` snapshot. Если source.updated_at > snapshot.dbt_valid_to -> строка изменилась. Требует надёжной updated_at в source. Дёшево.

Snapshot strategy: dbt сравнивает значения колонок из `check_cols` между source и snapshot. Любое изменение -> новая версия. Дороже timestamp (column-wise comparison), но не нужна updated_at. Gotcha: добавление новой колонки в check_cols ломает историю.

Snapshot config (1.9+): что делать с строками, исчезнувшими в source. Опции: `ignore` (default) — оставить с открытым dbt_valid_to (рудимент истории), `invalidate` — закрыть dbt_valid_to = now(), `new_record` — добавить новую строку с маркером удаления.

Колонка SCD2-snapshot: timestamp начала валидности данной версии строки. На первой версии = время первого snapshot run. Не NULL.

Колонка SCD2-snapshot: timestamp закрытия версии. NULL для текущей версии (по умолчанию) или `9999-12-31` если включён `dbt_valid_to_current`. Закрытая версия имеет конкретный timestamp = время следующего snapshot run.

Snapshot config (1.9+): значение dbt_valid_to для текущих (открытых) версий. Например, `2199-12-31`. Решает проблему NULL в date range queries (NULL > date всегда False).

Колонка SCD2-snapshot: surrogate key версии строки (hash от unique_key + dbt_valid_from). Уникален per row per version. Используется в downstream JOIN при time-travel queries.

Snapshot config (1.9+): кастомизация имён мета-колонок. Например, `{dbt_valid_from: valid_from, dbt_valid_to: valid_to}` для intgeration с downstream BI, ожидающим конкретные имена.

Legacy alias hard_deletes=invalidate (до 1.9). При удалении из source закрывает dbt_valid_to. После 1.9 рекомендуется писать новый синтаксис `hard_deletes: invalidate`.

Конфиг `contract: {enforced: true}` — dbt проверяет, что compiled SQL возвращает колонки в точности с типами из yml schema. Несовпадение типа = build fail. Гарантия стабильности схемы для downstream consumers.

Конфиг колонок модели: `not_null`, `unique`, `primary_key`, `foreign_key`, `check`. Если warehouse поддерживает — применяются как DDL constraints. Иначе — metadata-only (false sense of security). DuckDB: частично (FK не работает на MotherDuck).

Включение `contract: {enforced: true}`. Парс-time проверка соответствия `columns:` секции в yml реальному выводу модели. Без enforced контракт декларативный (доки), не валидируется.

Mesh-feature: множественные версии одной модели — `model.v1.sql`, `model.v2.sql`. У каждой свой контракт и downstream consumers. Используется для backward-compatible эволюции схемы.

Yaml-конфиг model versions: какая версия резолвится при `ref('model')` без явного `version`. Если не выставлен — резолвится в max version. Контролирует, когда consumers автоматически переключаются на новую версию.

Yaml-конфиг конкретной версии модели: дата, после которой использование версии вызывает warning. Помогает плавно мигрировать consumers перед удалением старой версии.

Синтаксис `ref('model', v=1)` — явное обращение к конкретной версии. Если не указан v — берётся latest_version. Производит зависимость от конкретной версии в manifest, видно в lineage.

Yaml-конфиг группировки моделей для access control в Mesh. Группа имеет owner и определяет логическую границу. Используется парой с access (public/protected/private).

Yaml-конфиг модели: `public` (можно ref из любого проекта), `protected` (только внутри проекта, default), `private` (только внутри group). Применяется в Mesh для контроля cross-project boundaries.

Mesh: ref на модель из другого dbt-проекта через `ref('upstream_project', 'model_name')`. Требует, чтобы upstream-модель имела `access: public` и был настроен `dependencies.yml`.

Архитектурный паттерн dbt: разделение монолита на несколько проектов с явными контрактами и groups + access. Каждая команда владеет своим проектом, продуктовые границы — на уровне `access: public` моделей.

Yaml-описание downstream consumer dbt-моделей: BI-дашборд, ML-пайплайн, application. Не материализуется, лишь регистрируется в lineage и manifest. Используется для impact analysis и для source freshness gates.

Проверка свежести source: dbt запускает `SELECT MAX(timestamp) FROM source` и сравнивает с threshold (warn_after/error_after). Часть production-job — если source устарел, run завершается с error.

Yaml-конфиг source: `warn_after` и `error_after` с {count, period}. Например, `error_after: {count: 24, period: hour}` -> если source старше 24ч, fail. Запускается через `dbt source freshness`.

Тест из dbt 1.8+: моки upstream-моделей через `given:`, проверка `expect:` напрямую на SQL логику. Запускается на parse-time через `dbt test --select test_type:unit`. Не требует данных в warehouse.

Unit test fixtures: данные в `tests/fixtures/*.csv` или inline в yml. Подставляются как mock upstream-моделей через `given:` секцию. Поддерживают dict / csv / sql формат.

Unit test config: переопределение vars / env_vars / macros для конкретного теста. Например, `overrides: {vars: {is_test: true}}` — позволяет mockать поведение Jinja-конфигов.

Тест из `tests/generic/*.sql` с Jinja-аргументами. Например, test_positive_value: `SELECT * FROM {{ model }} WHERE {{ column_name }} <= 0`. Возвращает rows, которые fail. Используется через yml как стандартный тест.

Config теста: `error` (CI fail) или `warn` (CI зелёный, лог-warning). Используется когда нужна градация: бизнес-правила — error, soft-проверки — warn.

Config теста: пороги, при которых тест становится `error` или `warn`. Например, `error_if: '>10'`, `warn_if: '>0'` — 1-10 fail = warn, 11+ = error. Реализует tolerance бизнес-правил.

Config теста: `store_failures: true` -> результаты упавших тестов сохраняются в schema `<project>_dbt_test__audit.<test_name>`. Позволяет анализировать, какие именно строки сломали бизнес-правило.

Config теста (1.9+): материализация failure-таблиц: `table` (default), `view`, `ephemeral`. Контролирует, как долго хранятся данные тестов и есть ли они физически.

Config теста: ограничение rows, которые тест возвращает. По умолчанию — все. `limit: 10` — быстрее для производительности, но видишь только sample.

Package с расширенным набором тестов: `expect_column_values_to_be_in_set`, `expect_table_row_count_to_equal`, `expect_column_distinct_count_to_be_greater_than`. Inspired by Great Expectations. Канон для data quality.

Стандартный package: `surrogate_key`, `union_relations`, `pivot`, `equal_rowcount` тест, `unique_combination_of_columns` тест. Must-have в большинстве проектов.

Package для миграций / refactoring моделей: сравнение old vs new модели — diff на row counts, value-level, dim parity. `compare_relations`, `compare_column_values` макросы.

Package для авто-генерации yml: `generate_source` строит yml для existing schema, `generate_model_yaml` — для existing model. Полезно для bootstrap нового проекта или нового dataset.

Package, который проверяет проект на best practices: testing coverage, naming, structure, performance. Запускается как `dbt build --select package:dbt_project_evaluator`. Полезно в CI.

Engine Semantic Layer dbt: компилирует semantic_models + metrics + saved_queries в SQL. Стандартизирует определения метрик. CLI: `mf query --metrics revenue --group-by metric_time__day`.

Yaml-объект Semantic Layer: связывает physical model с измерениями (entities, dimensions, measures). Каждая бизнес-сущность (customer, order) — один semantic_model.

Поле semantic_model: ключ (primary/foreign/unique/natural), по которому модели joinятся в семантическом графе. Тип определяет роль в JOIN: primary — собственный ключ, foreign — указатель на другую entity.

Поле semantic_model: атрибут для group-by или filter. Может быть categorical (status) или time (created_at). Time dimension с granularity (day/week/month) — для агрегации по времени.

Поле semantic_model: численная агрегация, которая может быть использована в metric. Имеет `agg` (sum/count/avg/max/min), `expr` (SQL-выражение). Атомарный кирпич для построения метрик.

Yaml-объект Semantic Layer: бизнес-определение KPI. Типы: simple (один measure), ratio (numerator/denominator), cumulative (running sum с window), derived (формула из других метрик).

Метрика на одном measure: `revenue` = sum(order_amount). Самый базовый тип, чаще всего используется как кирпич для derived и ratio метрик.

Метрика с числителем и знаменателем: `aov` = revenue / order_count. MetricFlow гарантирует корректный JOIN и предотвращает Cartesian, агрегируя numerator/denominator независимо.

Running sum / accumulation метрика: `mtd_revenue` — month-to-date. Параметры `window` (фиксированное окно) и `grain_to_date` (нарастающим итогом до начала периода).

Метрика-формула, скомбинированная из других метрик: `profit` = revenue - costs. Все компоненты резолвятся MetricFlow в один query.

Yaml-объект Semantic Layer: фиксированный набор metrics + group-by + filters, который можно запустить через `mf query --saved-query`. Использовать для регулярных дашбордов и экспортов.

Часть saved_query: материализация результата как table/view в warehouse через `mf export`. Закрывает gap между MetricFlow и legacy BI, которому нужен flat dataset.

Виртуальное измерение MetricFlow: универсальный time-axis, агрегирующий разные source-time колонки в семантический граф. Используется как `--group-by metric_time__day`.

Флаг `--sample={mode}` в 1.10+: запуск моделей на сэмпле данных (e.g. `time-window={days_ago:7}`). Ускоряет dev-итерации. Конфиг модели может объявлять, что она поддерживает sampling.

Mechanism для warehouse-specific macros: один и тот же макрос имеет реализации `default__foo`, `snowflake__foo`, `bigquery__foo`. dbt выбирает корректную по active adapter. Каноничный паттерн в dbt-utils.

Аргумент dispatch: список packages, в которых dbt ищет реализацию макроса. Без него dbt берёт первую попавшуюся; с правильным search_order вы переопределяете макросы из dbt-utils.

Jinja-макрос: выполняет SQL во время parse/run и возвращает Agate-table. Используется для динамической генерации SQL (например, получить список колонок из information_schema).

Jinja-блок `{% call statement('name', fetch_result=True) %}SELECT ...{% endcall %}` — выполняет SQL без формирования модели. Результат доступен через `load_result('name')`. Низкоуровневый эквивалент run_query.

Hook: список SQL/Jinja-выражений, выполняемых перед началом dbt run/build. Используется для инициализации (CREATE SCHEMA, GRANT), audit-логов.

Hook: SQL/Jinja-выражения после окончания run. Часто — VACUUM/ANALYZE, удаление temp-объектов, запись метрик run в audit-таблицу.

Model-level hooks: SQL перед/после материализации конкретной модели. Например, post-hook GRANT SELECT ON {{this}} TO bi_role.

Config: `persist_docs: {relation: true, columns: true}` — dbt записывает description как COMMENT в warehouse. Удобно для BI-инструментов, читающих native catalog. DuckDB поддерживает relation, не все warehouses — column comments.

Reusable description: `{% docs my_block %}Это описание...{% enddocs %}` в `.md` файле, затем `description: '{{ doc("my_block") }}'` в yml. Защищает от копипасты описаний между моделями.

Override-макрос: контролирует, как dbt именует target schema. Без override dbt объединяет profile.schema + model.schema суффиксом. Каноничная замена: prod без суффикса, остальное — c суффиксом.

Config модели: `grants: {select: ['bi_role', 'analyst_role']}`. dbt применяет GRANT после материализации. С `+` (cumulative) добавляет к существующим, без — заменяет (опасно: отозвать чужой grant).

Jinja-функция: `{{ env_var('NAME', 'default') }}` читает переменную окружения. Без default в production CI падает с непонятной ошибкой; с default — graceful.

Jinja-переменная: имя active target (dev/ci/prod). Используется для conditional logic: `{% if target.name == 'prod' %}...{% endif %}`. В SQL hard-code = невозможно тестировать.

Глобальные/per-package переменные dbt: `vars: {is_partner: true}` в `dbt_project.yml`. Переопределяются через `--vars '{is_partner: false}'` в CLI. Доступны в Jinja как `{{ var('is_partner') }}`.

Framework для git-хуков: pre-commit-config.yml объявляет хуки (sqlfmt, sqlfluff, dbt-checkpoint), которые запускаются при `git commit`. Без `pre-commit install` хуки молча игнорируются.

Линтер SQL с поддержкой Jinja через `dbt` templater. Проверяет правила (capitalization, indent, имена). Без templater'а — false positives на dbt-шаблонах.

Форматтер SQL (single-line по умолчанию, multi-line при превышении width). Быстрее sqlfluff, без правил, только формат. Pairs хорошо с sqlfluff (формат + lint).

Set of pre-commit хуков specifically для dbt: check-script-has-no-table-name (no hard-coded refs), check-model-has-tests, check-source-has-freshness.

Платформа CI/CD от GitHub: workflows в `.github/workflows/*.yml`. Каноничный паттерн dbt: matrix-run на разные targets, кэш `~/.dbt`, manifest storage между runs, Slim CI.

Линтер для GitHub Actions YAML: проверяет syntax, shell-выражения, валидность `uses: action@v1`. Полезен в pre-commit и в первом шаге workflow.

Persistence стратегии baseline manifest для Slim CI: S3 (durable, IAM), gh-pages branch (zero-cost, public), CI artifacts (TTL ограничен), package registry. Обновляется после каждого успешного prod-deploy.

Managed offering dbt Labs: IDE в браузере, Jobs scheduler, Explorer (lineage UI), API, native Slim CI, Semantic Layer API. Платно. DuckDB официально не поддерживается.

Scheduled / triggered runs в dbt Cloud: типы — Deploy job (prod build), CI job (PR-trigger Slim CI), Merge job. Имеют notifications, webhooks, retry policy.

dbt Cloud UI для lineage и discovery: navigable DAG, model docs, query history, change impact analysis. Build на основе manifest + catalog.

dbt Cloud feature: HTTP POST на ваш endpoint при событии (job.run.completed). Используется для downstream automation: trigger BI refresh, alert в Slack.

Native Rust-based engine dbt 2026: rewrite dbt-core с упором на performance (10x parse speed), better state management, less Python overhead. Stable на Snowflake (GA), preview elsewhere.

Сериализованные файлы dbt в `target/`: manifest.json, run_results.json, catalog.json, sources.json, semantic_manifest.json. Используются для metadata-driven автоматизации, lineage, observability.

Materialization: модель не материализуется в warehouse, а inline'ится как CTE в downstream-моделях. Хороша для логических промежуточных шагов; плоха для деба и unit-тестов.

Jinja-функция: `{{ ref('model_name') }}` резолвится в полностью квалифицированное имя `database.schema.model_name`. Создаёт edge в DAG. На CI с `--defer` может резолвиться в prod-схему вместо CI-схемы.

Jinja-функция: `{{ source('source_name', 'table_name') }}` резолвится в external table из source yml. Не создаёт зависимости на dbt-модель, но добавляет node типа source в DAG.

Mesh-config: список upstream-проектов для cross-project ref. Альтернатива `packages.yml` для проектов; работает только с dbt Cloud или native Fusion.

Reusable dbt-проект, опубликованный в hub.getdbt.com или git. Объявляется в `packages.yml`, устанавливается через `dbt deps` в `dbt_packages/`. Может содержать модели, макросы, тесты.

Best practice: фиксировать версию package (`version: 1.5.0`) вместо `>=1.0.0`. Защищает от breaking changes в зависимостях.

Open table format Apache Iceberg: ACID, time travel, schema evolution. Поддерживается warehouses (Snowflake, Athena, Databricks). dbt 1.11 на Snowflake: views только; incremental — не поддерживается.

Lake-format DuckDB (April 2026): партиционирование на Parquet, ACID через manifest-snapshot, query через DuckDB engine. Альтернатива Iceberg для small-scale lakes.

Hosted DuckDB cloud: `md:` connection string, scaled storage и compute. Production-deployment DuckDB. Не поддерживает FK constraints, custom extensions, dbt.listagg.

Convention: yml-файл рядом с моделями описывает их columns, tests, descriptions. Альтернативные имена: schema.yml, _<dir>_models.yml. dbt парсит все *.yml в models/.

Convention: yml-файл рядом с staging описывает sources (внешние таблицы): database, schema, tables, freshness. Используется для `source()` references.

Convention: yml-файл с описанием exposures (BI, ML, apps). Регистрирует downstream consumer в lineage и manifest.

Архитектурный паттерн: bronze (raw) -> silver (staging/cleaned) -> gold (marts/aggregated). dbt-convention: `staging/` (silver) + `intermediate/` (middle) + `marts/` (gold).

Слой dbt-проекта: 1:1 с raw sources, минимальная трансформация (rename, type cast, easy filters). Имена: `stg_<source>__<table>`. Output только для intermediate/marts, не для BI.

Слой dbt-проекта: между staging и marts — business logic, joins, расчёты. Имена: `int_<purpose>_<verb>`. Не показываются в BI. Часто ephemeral.

Слой dbt-проекта: финальные таблицы для BI / analytics consumers. Конвенции: `fct_<name>` (facts, transaction-level), `dim_<name>` (dimensions, lookups). Materialized as table/incremental.

Стандарт dbt-сообщества: `stg_<source>__<table>`, `int_<purpose>`, `fct_<name>`, `dim_<name>`. Чёткие префиксы помогают navigation, ownership, automated tools (dbt_project_evaluator).