# SQL-модели

## Связанные справочные документы

* [Конфигурации моделей](https://docs.getdbt.tech/reference/model-configs.md)
* [Свойства моделей](https://docs.getdbt.tech/reference/model-properties.md)
* [Команда `run`](https://docs.getdbt.tech/reference/commands/run.md)
* [Функция `ref`](https://docs.getdbt.tech/reference/dbt-jinja-functions/ref.md)

## Начало работы

Создание ваших первых моделей

Если вы новичок в dbt, мы рекомендуем вам прочитать [руководство по быстрому старту](https://docs.getdbt.tech/guides.md), чтобы создать ваш первый проект dbt с моделями.

Возможности Python в dbt являются расширением его возможностей с SQL моделями. Если вы новичок в dbt, мы рекомендуем сначала прочитать эту страницу, прежде чем переходить к: ["Python модели"](https://docs.getdbt.tech/docs/build/python-models.md).

SQL-модель — это инструкция `select`. Модели определяются в файлах `.sql` (обычно в каталоге `models`):

* Каждый файл `.sql` содержит одну модель / инструкцию `select`
* Имя модели наследуется от имени файла и должно совпадать с *именем файла* модели — с учётом регистра. Любое несоответствие регистра может помешать dbt корректно применить конфигурации и повлиять на метаданные в [Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md).
* Мы настоятельно рекомендуем использовать в именах моделей символы подчёркивания, а не точки. Например, используйте `models/my_model.sql` вместо `models/my.model.sql`.
* Модели можно размещать в подкаталогах каталога `models`.
* Начиная с dbt v1.12, можно добавлять к файлам `.sql` суффиксы в стиле Jinja (`.j2`, `.jinja`, `.jinja2`) (например, `my_model.sql.j2`), включив флаг [`allow_jinja_file_extensions`](https://docs.getdbt.tech/reference/global-configs/behavior-flags/allow_jinja_file_extensions.md).

Рекомендации по именованию см. в разделе [Стиль моделей dbt](https://docs.getdbt.tech/best-practices/how-we-style/1-how-we-style-our-dbt-models.md).

Когда вы выполняете [команду `dbt run`](https://docs.getdbt.tech/reference/commands/run.md), dbt создаст эту модель data warehouse обернув её в оператор `create view as` или `create table as`.

Например, рассмотрим эту модель `customers`:

models/customers.sql

```sql
with customer_orders as (
    select
        customer_id,
        min(order_date) as first_order_date,
        max(order_date) as most_recent_order_date,
        count(order_id) as number_of_orders

    from jaffle_shop.orders

    group by 1
)

select
    customers.customer_id,
    customers.first_name,
    customers.last_name,
    customer_orders.first_order_date,
    customer_orders.most_recent_order_date,
    coalesce(customer_orders.number_of_orders, 0) as number_of_orders

from jaffle_shop.customers

left join customer_orders using (customer_id)
```

Когда вы выполняете `dbt run`, dbt создаст это как *представление* с именем `customers` в вашей целевой схеме:

```sql
create view dbt_alice.customers as (
    with customer_orders as (
        select
            customer_id,
            min(order_date) as first_order_date,
            max(order_date) as most_recent_order_date,
            count(order_id) as number_of_orders

        from jaffle_shop.orders

        group by 1
    )

    select
        customers.customer_id,
        customers.first_name,
        customers.last_name,
        customer_orders.first_order_date,
        customer_orders.most_recent_order_date,
        coalesce(customer_orders.number_of_orders, 0) as number_of_orders

    from jaffle_shop.customers

    left join customer_orders using (customer_id)
)
```

Почему *представление* с именем `dbt_alice.customers`? По умолчанию dbt будет:

* Создавать модели как представления
* Создавать модели в целевой схеме, которую вы определяете
* Использовать имя вашего файла как имя представления или таблица в базе данных

Вы можете использовать *конфигурации*, чтобы изменить любое из этих поведений — об этом позже.

### Часто задаваемые вопросы

Как посмотреть SQL, который выполняет dbt?

Чтобы посмотреть SQL, который выполняет dbt, вы можете заглянуть в:

* dbt:
  * В выводе запуска нажмите на название модели, а затем выберите «Details»

* dbt v1:

  * Директория `target/compiled/` для скомпилированных операторов `select`
  * Директория `target/run/` для скомпилированных операторов `create`
  * Файл `logs/dbt.log` для подробного логирования

Нужно ли создавать целевую схему перед запуском dbt?

Нет! dbt проверит, существует ли схема, когда она запускается. Если схема не существует, dbt создаст её для вас.

Если я перезапущу dbt, будет ли простой, пока модели перестраиваются?

Нет! SQL, который dbt генерирует за кулисами, гарантирует, что любые связи заменяются атомарно (т.е. ваши бизнес-пользователи не испытают никакого простоя).

Реализация этого процесса варьируется в зависимости от каждого хранилища данных, проверьте [логи](https://docs.getdbt.tech/faqs/Runs/checking-logs.md), чтобы увидеть, какой SQL выполняет dbt.

Что произойдет, если в моем SQL-запросе ошибка или я получу ошибку базы данных?

Если в вашем SQL есть ошибка, dbt вернет ошибку, которую возвращает ваша база данных.

```shell
$ dbt run --select customers
Running with dbt=1.9.0
Found 3 models, 9 tests, 0 snapshots, 0 analyses, 133 macros, 0 operations, 0 seed files, 0 sources

14:04:12 | Concurrency: 1 threads (target='dev')
14:04:12 |
14:04:12 | 1 of 1 START view model dbt_alice.customers.......................... [RUN]
14:04:13 | 1 of 1 ERROR creating view model dbt_alice.customers................. [ERROR in 0.81s]
14:04:13 |
14:04:13 | Finished running 1 view model in 1.68s.

Completed with 1 error and 0 warnings:

Database Error in model customers (models/customers.sql)
  Syntax error: Expected ")" but got identifier `your-info-12345` at [13:15]
  compiled SQL at target/run/jaffle_shop/customers.sql

Done. PASS=0 WARN=0 ERROR=1 SKIP=0 TOTAL=1
```

Любые модели, зависящие от этой модели, также будут пропущены. Используйте сообщение об ошибке и [скомпилированный SQL](https://docs.getdbt.tech/faqs/Runs/checking-logs.md) для отладки любых ошибок.

В каком SQL-диалекте писать мои модели? Или какой SQL-диалект использует dbt?

dbt может казаться магией, но на самом деле это не так. Под капотом он выполняет SQL в вашем собственном хранилище данных — ваши данные не обрабатываются за пределами вашего хранилища.

Таким образом, ваши модели должны использовать **SQL-диалект вашей собственной базы данных**. Затем, когда dbt оборачивает ваши `select` выражения в соответствующие DDL или DML, он будет использовать правильный DML для вашего хранилища — вся эта логика уже заложена в dbt.

Вы можете найти больше информации о базах данных, платформах и движках запросов, которые поддерживает dbt, в документации [Поддерживаемые платформы данных](https://docs.getdbt.tech/docs/supported-data-platforms.md).

Хотите углубиться в то, как это работает? Рассмотрим фрагмент SQL, который работает на каждом хранилище:

models/test\_model.sql

```sql
select 1 as my_column
```

Чтобы заменить существующую таблица, вот *иллюстративный* пример SQL, который dbt выполнит на разных хранилищах (фактический SQL может быть гораздо сложнее этого!)

### Redshift

```sql
-- на redshift нельзя создать или заменить, поэтому используйте транзакцию для выполнения этого атомарно

begin;

create table "dbt_alice"."test_model__dbt_tmp" as (
    select 1 as my_column
);

alter table "dbt_alice"."test_model" rename to "test_model__dbt_backup";

alter table "dbt_alice"."test_model__dbt_tmp" rename to "test_model"

commit;

begin;

drop table if exists "dbt_alice"."test_model__dbt_backup" cascade;

commit;
```

### BigQuery

```sql

-- Сделайте API-вызов для создания набора данных (нет интерфейса DDL для этого)!!;

create or replace table `dbt-dev-87681`.`dbt_alice`.`test_model` as (
  select 1 as my_column
);
```

### Snowflake

```sql
create schema if not exists analytics.dbt_alice;

create or replace table analytics.dbt_alice.test_model as (
    select 1 as my_column
);
```

## Настройка моделей

Конфигурации — это «настройки моделей», которые вы можете задавать в файле `dbt_project.yml`, а также непосредственно в файле модели с помощью блока `config`. Примеры таких конфигураций включают:

* Изменение материализация используемого моделью — [материализация](https://docs.getdbt.tech/docs/build/materializations.md) определяет SQL, который dbt использует для создания модели в вашем хранилище данных.
* Создание моделей в отдельных [схемах](https://docs.getdbt.tech/docs/build/custom-schemas.md).
* Применение [тегов](https://docs.getdbt.tech/reference/resource-configs/tags.md) к модели.

Следующая диаграмма показывает пример структуры каталогов папки `models`:

```text
models
├── staging
└── marts
    └── marketing
```

Ниже приведён пример конфигурации модели:

dbt\_project.yml

```yaml
name: jaffle_shop
config-version: 2
...

models:
  jaffle_shop: # это соответствует `name:`` конфигурации
    +materialized: view # это применяется ко всем моделям в текущем проекте
    marts:
      +materialized: table # это применяется ко всем моделям в каталоге `marts/`
      marketing:
        +schema: marketing # это применяется ко всем моделям в каталоге `marts/marketing/`
```

models/customers.sql

```sql

{{ config(
    materialized="view",
    schema="marketing"
) }}

with customer_orders as ...
```

Важно отметить, что конфигурации применяются иерархически — конфигурация, примененная к подкаталогу, переопределит любые общие конфигурации.

Вы можете узнать больше о конфигурациях в [справочной документации](https://docs.getdbt.tech/reference/model-configs.md).

### Часто задаваемые вопросы

Какие материализации доступны в dbt?

В dbt есть пять встроенных материализаций: `view`, `table`, `incremental`, `ephemeral` и `materialized_view`. Подробнее о каждом из этих вариантов можно узнать в документации по [материализациям](https://docs.getdbt.tech/docs/build/materializations.md).

Вы также можете создавать собственные [пользовательские материализации](https://docs.getdbt.tech/guides/create-new-materializations.md). Это расширенная возможность dbt.

Какие существуют конфигурации моделей?

Вы также можете настроить:

* [теги](https://docs.getdbt.tech/reference/resource-configs/tags.md) для поддержки легкой категоризации и выбора графа
* [пользовательские схемы](https://docs.getdbt.tech/reference/resource-properties/schema.md) для разделения ваших моделей по нескольким схемам
* [алиасы](https://docs.getdbt.tech/reference/resource-configs/alias.md), если имя вашего представление/таблица должно отличаться от имени файла
* Фрагменты SQL, которые выполняются в начале или в конце модели, известные как [хуки](https://docs.getdbt.tech/docs/build/hooks-operations.md)
* Конфигурации, специфичные для хранилища, для повышения производительности (например, ключи `sort` и `dist` на Redshift, `partitions` на BigQuery)

Ознакомьтесь с документацией по [конфигурациям моделей](https://docs.getdbt.tech/reference/model-configs.md), чтобы узнать больше.

## Построение зависимостей между моделями

Вы можете строить зависимости между моделями, используя функцию [`ref`](https://docs.getdbt.tech/reference/dbt-jinja-functions/ref.md) вместо имен таблиц в запросе. Используйте имя другой модели в качестве аргумента для `ref`.

### Модель

models/customers.sql

```sql
with customers as (

    select * from {{ ref('stg_customers') }}

),

orders as (

    select * from {{ ref('stg_orders') }}

),

...
```

### Скомпилированный код в dev

```sql
create view dbt_alice.customers as (
  with customers as (

      select * from dbt_alice.stg_customers

  ),

  orders as (

      select * from dbt_alice.stg_orders

  ),

  ...
)

...
```

### Скомпилированный код в prod

```sql
create view analytics.customers as (
  with customers as (

      select * from analytics.stg_customers

  ),

  orders as (

      select * from analytics.stg_orders

  ),

  ...
)

...
```

dbt использует функцию `ref` для:

* Определения порядка выполнения моделей, создавая ориентированный ациклический граф (DAG).

[![DAG для нашего dbt проекта](/img/dbt-dag.png?v=2 "DAG для нашего dbt проекта")](#)DAG для нашего dbt проекта

* Управления отдельными средами — dbt заменит модель, указанную в функции `ref`, на имя базы данных для таблица (или представления). Важно, что это учитывает среду — если вы запускаете dbt с целевой схемой, названной `dbt_alice`, он будет выбирать из вышестоящей таблицы в той же схеме. Посмотрите на вкладки выше, чтобы увидеть это в действии.

Кроме того, функция `ref` поощряет вас писать модульные преобразования, чтобы вы могли повторно использовать модели и уменьшить повторяющийся код.

## Тестирование и документирование моделей

Вы также можете документировать и тестировать модели — перейдите к разделу о [тестировании](https://docs.getdbt.tech/docs/build/data-tests.md) и [документировании](https://docs.getdbt.tech/docs/build/documentation.md) для получения дополнительной информации.

## Дополнительные часто задаваемые вопросы

Есть ли примеры dbt моделей?

Да!

* **Руководство по быстрому старту:** Вы можете создать собственный пример проекта dbt, следуя [руководству по быстрому старту](https://docs.getdbt.tech/docs/get-started-dbt.md)
* **Jaffle Shop:** Демонстрационный проект (тесно связанный с учебным руководством) для вымышленного интернет-магазина. Инструкции по клонированию см. в разделе [Клонирование примера проекта Jaffle Shop](https://docs.getdbt.tech/guides/clone-jaffle-shop.md). Также на GitHub доступны [основной исходный код](https://github.com/dbt-labs/jaffle-shop) и [исходный код с использованием DuckDB](https://github.com/dbt-labs/jaffle_shop_duckdb).
* **GitLab:** Внутренний проект dbt компании GitLab имеет открытый исходный код и служит отличным примером масштабного использования dbt ([исходный код](https://gitlab.com/gitlab-com/content-sites/handbook/blob/main/content/handbook/enterprise-data/platform/dbt-guide.md))
* **dummy-dbt:** Контейнеризированный проект dbt, который наполняет базу данных Sakila в Postgres и создает seed-данные, модели, снимки и тесты dbt. Проект можно использовать для тестирования и экспериментов ([исходный код](https://github.com/gmyrianthous/dbt-dummy))
* **Google Analytics 4:** Демонстрационный проект, который преобразует данные, экспортированные из Google Analytics 4 в BigQuery, в различные модели ([исходный код](https://github.com/stacktonic-com/stacktonic-dbt-example-project), [документация](https://stacktonic.com/article/google-analytics-big-query-and-dbt-a-dbt-example-project))
* **Make Open Data:** Готовый к промышленной эксплуатации ELT-проект с тестами, документацией и CI/CD (GHA), посвященный открытым данным Франции (жилье, демография, география и т. д.). Его можно использовать для обучения работе с большими объемами неоднозначных данных. Приветствуется участие в развитии проекта ([исходный код](https://github.com/make-open-data/make-open-data).

Если у вас есть пример проекта, который вы хотите добавить в этот список, предложите правку, нажав **Edit this page** ниже.

Могу ли я хранить свои модели в директории, отличной от \`models\`, в моем проекте?

По умолчанию dbt ожидает, что файлы, определяющие ваши модели, будут находиться в поддиректории `models` вашего проекта.

Чтобы изменить это, обновите настройку [model-paths](https://docs.getdbt.tech/reference/project-configs/model-paths.md) в файле `dbt_project.yml` следующим образом:

dbt\_project.yml

```yml
model-paths: ["transformations"]
```

Могу ли я создавать свои модели в схеме, отличной от целевой, или распределять модели по нескольким схемам?

Да! Используйте конфигурацию [schema](https://docs.getdbt.tech/reference/resource-configs/schema.md) в файле `dbt_project.yml` или в блоке `config`:

dbt\_project.yml

```yml
name: jaffle_shop
...

models:
  jaffle_shop:
    marketing:
+schema: marketing # модели в подкаталоге `models/marketing/` будут использовать схему marketing
```

models/customers.sql

```sql
{{
  config(
    schema='core'
  )
}}
```

Должны ли имена ресурсов, используемых в ref, быть уникальными?

В рамках одного проекта: да! Чтобы построить зависимости между ресурсами (такими как модели, семена и снимки), вам нужно использовать функцию `ref` и передать в нее имя ресурса в качестве аргумента. dbt использует это имя ресурса для уникального разрешения `ref` на конкретный ресурс. В результате, эти имена ресурсов должны быть уникальными, *даже если они находятся в разных папках*.

Ресурс в одном проекте может иметь то же имя, что и ресурс в другом проекте (установленном как зависимость). dbt использует имя проекта для уникальной идентификации каждого ресурса. Мы называем это "пространством имен". Если вы используете `ref` для ресурса с дублированным именем, он будет разрешен в ресурс в том же пространстве имен (пакет или проект) или вызовет ошибку из-за неоднозначной ссылки. Используйте [двухаргументный `ref`](https://docs.getdbt.tech/reference/dbt-jinja-functions/ref.md#ref-project-specific-models) для устранения неоднозначности ссылок, указав пространство имен.

Эти ресурсы все равно должны размещаться в разных местах в хранилище данных. Прочтите документацию по [пользовательским псевдонимам](https://docs.getdbt.tech/docs/build/custom-aliases.md) и [пользовательским схемам](https://docs.getdbt.tech/docs/build/custom-schemas.md) для получения подробной информации о том, как этого добиться.

Как удалить удаленные модели из моего хранилища данных?

Если вы удаляете модель из вашего dbt проекта, dbt не удаляет автоматически связь из вашей схемы. Это означает, что в схемах, которые создает dbt, могут остаться лишние объекты, что может запутать других пользователей.

(Это также может произойти, когда вы переключаете модель с представление или таблица на эфемерную)

Когда вы удаляете модели из вашего dbt проекта, вам следует вручную удалить связанные связи из вашей схемы.

Как я должен организовать свой проект, когда создаю больше моделей? Как я должен называть свои модели?

Нет единственного лучшего способа структурировать проект! Каждая организация уникальна.

Если вы только начинаете, ознакомьтесь с тем, как мы (dbt Labs) [структурируем наши dbt проекты](https://docs.getdbt.tech/best-practices/how-we-structure/1-guide-overview.md).

Если модели могут быть только \`select\` запросами, как вставлять записи?

Для тех, кто приходит из парадигмы ETL (Extract Transform Load), часто возникает желание писать преобразования в виде операторов `insert` и `update`. В сравнении с этим, dbt обернет ваш `select` запрос в оператор `create table as`, что может показаться контрпродуктивным.

* Если вы хотите использовать операторы `insert` для повышения производительности (то есть для уменьшения объёма обрабатываемых данных), рассмотрите возможность использования [инкрементальных моделей](https://docs.getdbt.tech/docs/build/incremental-models.md)
* Если вы хотите использовать операторы `insert`, поскольку ваши исходные данные постоянно меняются (например, для создания «медленно изменяющихся измерений типа 2»), рассмотрите возможность [создания снимков исходных данных](https://docs.getdbt.tech/docs/build/sources.md#source-data-freshness) и построения моделей на основе этих снимков.

Почему я не могу просто писать DML в своих трансформациях?

#### Операторы `select` делают трансформации доступными

Больше людей умеют писать операторы `select`, чем DML, что делает слой трансформации доступным для большего числа людей!

#### Написание хорошего DML сложно

Если вы сами пишете DDL / DML, вы можете столкнуться с такими проблемами, как:

* Что произойдет, если таблица уже существует? Или эта таблица уже существует как представление, но теперь я хочу, чтобы это была таблица?
* Что если схема уже существует? Или, стоит ли мне проверять, существует ли схема?
* Как я могу заменить модель атомарно (так, чтобы не было простоя для тех, кто запрашивает таблицу)?
* Что если я хочу параметризовать свою схему, чтобы запускать эти трансформации в среде разработки?
* В каком порядке мне нужно запускать эти операторы? Если я запускаю `cascade`, не сломает ли это другие вещи?

Каждую из этих проблем *можно* решить, но вряд ли это будет лучшим использованием вашего времени.

#### dbt делает больше, чем просто генерирует SQL

Вы можете тестировать свои модели, генерировать документацию, создавать снимки и многое другое!

#### Вы уменьшаете зависимость от поставщика

Диалекты SQL, как правило, больше всего расходятся в DML и DDL (а не в операторах `select`) — посмотрите пример [здесь](https://docs.getdbt.tech/faqs/Models/sql-dialect.md). Пишя меньше SQL, вы можете облегчить миграцию на новую технологию баз данных.

Если вам действительно нужно написать пользовательский DML, в dbt есть способы сделать это с помощью [пользовательских материализаций](https://docs.getdbt.tech/guides/create-new-materializations.md).

Как задать типы столбцов?

Просто приведите столбец к нужному типу в вашей модели:

```sql
select
    id,
    created::timestamp as created
from some_other_table
```

Этот вопрос может возникнуть, если вы привыкли выполнять такие запросы:

```sql
create table dbt_alice.my_table
  id integer,
  created timestamp;

insert into dbt_alice.my_table (
  select id, created from some_other_table
)
```

В сравнении, dbt создаст эту таблица с помощью оператора `create table as`:

```sql
create table dbt_alice.my_table as (
  select id, created from some_other_table
)
```

Пока ваши запросы в модели возвращают столбцы с правильным типом, создаваемая таблица также будет иметь правильный тип столбцов.

Для определения дополнительных параметров столбцов:

* Вместо того чтобы применять ограничения уникальности и not-null к вашим столбцам, используйте функциональность [тестирования данных](https://docs.getdbt.tech/docs/build/data-tests.md) в dbt, чтобы проверить, что ваши утверждения о модели верны.
* Вместо создания значений по умолчанию для столбца, используйте SQL для выражения значений по умолчанию (например, `coalesce(updated_at, current_timestamp()) as updated_at`)
* В редких случаях, когда вам *действительно* нужно изменить столбец (например, кодирование на уровне столбца в Redshift), рассмотрите возможность реализации этого через [post-hook](https://docs.getdbt.tech/reference/resource-configs/pre-hook-post-hook.md).
