# Быстрый старт с dbt при ручной установке

[Назад к гайдам](https://docs.getdbt.tech/guides.md)

[Menu ]()



## Введение

При использовании dbt, установленного вручную, вы будете редактировать файлы локально в редакторе кода и запускать проекты через интерфейс командной строки (CLI).

Если вы хотите редактировать файлы и запускать проекты в веб-среде интегрированной разработки dbt (Studio IDE), обратитесь к [руководствам по быстрому началу работы с dbt](https://docs.getdbt.tech/guides.md). Вы также можете разрабатывать проекты и выполнять команды dbt с помощью [dbt CLI](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md) — интерфейса командной строки на базе dbt.

### Предварительные требования

* Для работы с dbt важно знать основы работы с терминалом. В частности, вы должны понимать, как использовать команды `cd`, `ls` и `pwd`, чтобы легко перемещаться по структуре каталогов вашего компьютера.
* Установите dbt, следуя [инструкциям по установке](https://docs.getdbt.tech/docs/local/install-dbt.md) для вашей операционной системы.
* Выполните соответствующие шаги по настройке и загрузке данных из серии руководств по быстрому началу работы с dbt. Например, для BigQuery выполните шаги [Настройка (в BigQuery)](https://docs.getdbt.tech/guides/bigquery.md?step=2) и [Загрузка данных (BigQuery)](https://docs.getdbt.tech/guides/bigquery.md?step=3).
* [Создайте учетную запись GitHub](https://github.com/join), если у вас ее еще нет.

### Создание стартового проекта

После настройки BigQuery для работы с dbt вы готовы создать стартовый проект с примерами моделей, прежде чем создавать собственные модели.

## Создание репозитория

В следующих шагах в качестве Git‑провайдера для этого руководства используется [GitHub](https://github.com/), но вы можете использовать любой Git‑провайдер. Предполагается, что вы уже [создали аккаунт GitHub](https://github.com/join).

1. [Создайте новый репозиторий GitHub](https://github.com/new) с именем `dbt-tutorial`.

2. Выберите один из следующих вариантов (вы всегда сможете изменить эту настройку позже):

   * **Private (рекомендуется):** для защиты вашей среды и предотвращения публикации приватной информации (например, учетных данных).
   * **Public:** если вам нужно легко сотрудничать и делиться проектом с другими, особенно за пределами вашей организации.

3. Оставьте значения по умолчанию для всех остальных настроек.

4. Нажмите **Create repository**.

5. Сохраните команды из раздела «…or create a new repository on the command line», чтобы использовать их позже в шаге [Commit your changes](https://docs.getdbt.tech/guides/manual-install.md?step=6).

## Создание проекта

Узнайте, как создать проект с помощью последовательности команд в командной строке терминала. dbt включает команду `init`, которая помогает создать начальную структуру проекта dbt.

Чтобы создать ваш dbt проект:

1. Убедитесь, что у вас установлен dbt, и проверьте версию с помощью команды `dbt --version`:

```shell
dbt --version
```

2. Инициализируйте проект `jaffle_shop` с помощью команды `init`:

```shell
dbt init jaffle_shop
```

3. Перейдите в директорию вашего проекта:

```shell
cd jaffle_shop
```

4. Используйте `pwd`, чтобы убедиться, что вы находитесь в нужном месте:

```shell
$ pwd
> Users/BBaggins/dbt-tutorial/jaffle_shop
```

5. Откройте каталог проекта, созданный на предыдущих шагах и названный jaffle\_shop, в редакторе кода, например VS Code. В нём находятся папки, а также файлы `.sql` и `.yml`, созданные командой `init`.

[![Стартовый проект в текстовом редакторе](/img/starter-project-dbt-cli.png?v=2 "Стартовый проект в текстовом редакторе")](#)Стартовый проект в текстовом редакторе

6. dbt предоставляет следующие значения в файле `dbt_project.yml`:

dbt\_project.yml

```yaml
name: jaffle_shop # Измените с значения по умолчанию, `my_new_project`

...

profile: jaffle_shop # Измените с имени профиля по умолчанию, `default`

...

models:
    jaffle_shop: # Измените с `my_new_project`, чтобы соответствовать предыдущему значению для `name:`
    ...
```

## Подключение к BigQuery

При локальной разработке dbt подключается к вашему data warehouse с помощью [профиля](https://docs.getdbt.tech/docs/local/profiles.yml.md) — YAML-файла, содержащего все параметры подключения к вашему хранилищу данных.

1. Создайте файл в директории `~/.dbt/` с именем `profiles.yml`.
2. Переместите ваш ключевой файл BigQuery в эту директорию.
3. Скопируйте следующее и вставьте в новый файл profiles.yml. Убедитесь, что вы обновили значения, где это указано.

profiles.yml

```yaml
jaffle_shop: # это должно совпадать с профилем в вашем файле dbt_project.yml
    target: dev
    outputs:
        dev:
            type: bigquery
            method: service-account
keyfile: /Users/BBAGGINS/.dbt/KEYFILE_NAME.json # Замените на полный путь к вашему файлу ключа
            database: GCP_PROJECT_ID # Идентификатор вашего проекта Google Cloud
            schema: dbt_YOUR_NAME # Ваш набор данных для разработки, например dbt_bbaggins
            threads: 4
            location: US # Должно совпадать с расположением ваших наборов данных BigQuery
```

4. Запустите команду `debug` из вашего проекта, чтобы подтвердить, что вы можете успешно подключиться:

```shell
$ dbt debug
> Connection test: OK connection ok
```

[![Успешная команда dbt debug](/img/successful-dbt-debug.png?v=2 "Успешная команда dbt debug")](#)Успешная команда dbt debug

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

Моя команда данных использует другое хранилище данных. Как должен выглядеть мой файл profiles.yml для моего хранилища?

Структура профиля выглядит по-разному для каждого хранилища. Ознакомьтесь со страницей [Поддерживаемые платформы данных](https://docs.getdbt.tech/docs/supported-data-platforms.md) и перейдите в раздел `Profile Setup` для вашего хранилища.

Почему профили хранятся вне моего проекта?

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

Как назвать мой профиль?

Обычно мы используем название компании в качестве имени профиля, а затем используем целевые окружения (targets), чтобы различать `dev` и `prod`. Подробнее см. в документации об [окружениях в dbt v1](https://docs.getdbt.tech/docs/local/dbt-environments.md).

Как мне назвать свою цель?

Обычно мы используем цели (targets), чтобы различать запуски dbt в средах разработки и продакшена, называя эти цели `dev` и `prod` соответственно. Подробнее см. в документации по [управлению средами в dbt v1](https://docs.getdbt.tech/docs/local/dbt-environments.md).

Могу ли я использовать переменные окружения в своем профиле?

Да! Ознакомьтесь с документацией по [переменным окружения](https://docs.getdbt.tech/reference/dbt-jinja-functions/env_var.md) для получения дополнительной информации.

## Выполнение вашего первого dbt run

Наш пример проекта содержит некоторые примерные модели. Мы проверим, можем ли мы их запустить, чтобы убедиться, что все в порядке.

1. Введите команду `run`, чтобы построить примерные модели:

```shell
dbt run
```

Вы должны получить вывод, который выглядит следующим образом:

[![Успешная команда dbt run](/img/successful-dbt-run.png?v=2 "Успешная команда dbt run")](#)Успешная команда dbt run

## Зафиксируйте ваши изменения

Зафиксируйте ваши изменения, чтобы репозиторий содержал последний код.

1. Свяжите созданный вами репозиторий GitHub с вашим проектом dbt, выполнив следующие команды в Terminal. Убедитесь, что вы используете корректный git URL вашего репозитория, который вы должны были сохранить на шаге 5 в разделе [Create a repository](https://docs.getdbt.tech/guides/manual-install.md?step=2).

```shell
git init
git branch -M main
git add .
git commit -m "Create a dbt project"
git remote add origin https://github.com/USERNAME/dbt-tutorial.git
git push -u origin main
```

2. Вернитесь в ваш репозиторий GitHub, чтобы убедиться, что ваши новые файлы были добавлены.

### Создайте ваши первые модели

Теперь, когда вы настроили ваш примерный проект, вы можете перейти к интересной части — [созданию моделей](https://docs.getdbt.tech/docs/build/sql-models.md)! В следующих шагах вы возьмете пример запроса и превратите его в модель в вашем проекте dbt.

## Переключитесь на новую ветку git

Переключитесь на новую ветку git, чтобы работать над новым кодом:

1. Создайте новую ветку, используя команду `checkout` и передав флаг `-b`:

```shell
$ git checkout -b add-customers-model
>  Switched to a new branch `add-customer-model`
```

## Создайте вашу первую модель

Если вы хотите использовать ИИ для создания своей первой модели, ознакомьтесь с разделом [Создание модели с помощью dbt Wizard](#build-it-with-ai-using-dbt-wizard) ниже.

1. Откройте свой проект в предпочитаемом редакторе кода.
2. Создайте новый SQL-файл в каталоге `models` с именем `models/customers.sql`.
3. Вставьте следующий запрос в файл `models/customers.sql`.

### BigQuery

```sql
with customers as (

    select
        id as customer_id,
        first_name,
        last_name

    from `dbt-tutorial`.jaffle_shop.customers

),

orders as (

    select
        id as order_id,
        user_id as customer_id,
        order_date,
        status

    from `dbt-tutorial`.jaffle_shop.orders

),

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 orders

    group by 1

),

final as (

    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 customers

    left join customer_orders using (customer_id)

)

select * from final
```

### Databricks

```sql
with customers as (

    select
        id as customer_id,
        first_name,
        last_name

    from jaffle_shop_customers

),

orders as (

    select
        id as order_id,
        user_id as customer_id,
        order_date,
        status

    from jaffle_shop_orders

),

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 orders

    group by 1

),

final as (

    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 customers

    left join customer_orders using (customer_id)

)

select * from final
```

### Redshift

```sql
with customers as (

    select
        id as customer_id,
        first_name,
        last_name

    from jaffle_shop.customers

),

orders as (

    select
        id as order_id,
        user_id as customer_id,
        order_date,
        status

    from jaffle_shop.orders

),

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 orders

    group by 1

),

final as (

    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 customers

    left join customer_orders using (customer_id)

)

select * from final
```

### Snowflake

```sql
with customers as (

    select
        id as customer_id,
        first_name,
        last_name

    from raw.jaffle_shop.customers

),

orders as (

    select
        id as order_id,
        user_id as customer_id,
        order_date,
        status

    from raw.jaffle_shop.orders

),

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 orders

    group by 1

),

final as (

    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 customers

    left join customer_orders using (customer_id)

)

select * from final
```

Этот код SQL выполняет объединение данных из таблиц `customers` и `orders`, чтобы получить информацию о клиентах и их заказах. Он создает временные таблицы `customers`, `orders` и `customer_orders`, а затем объединяет их в финальную таблицу `final`, которая содержит идентификатор клиента, его имя и фамилию, дату первого и последнего заказа, а также количество заказов.

4. Из командной строки введите `dbt run`.

[![Успешное выполнение dbt из командной строки](/img/first-model-dbt-cli.png?v=2 "Успешное выполнение dbt из командной строки")](#)Успешное выполнение dbt из командной строки

Когда вы вернетесь в консоль BigQuery, вы можете выполнить `select` из этой модели.

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

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

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

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

* dbt v1:

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

Как dbt выбирает, в какой схеме строить мои модели?

По умолчанию dbt создаёт модели в вашей целевой схеме. Чтобы изменить целевую схему:

* Если вы разрабатываете в **dbt**, эти настройки задаются для каждого пользователя при первом использовании среды разработки.
* Если вы разрабатываете с помощью **dbt v1**, за это отвечает параметр `schema:` в вашем файле `profiles.yml`.

Если вы хотите распределить ваши модели по нескольким схемам, ознакомьтесь с документацией по [использованию пользовательских схем](https://docs.getdbt.tech/docs/build/custom-schemas.md).

Примечание: в BigQuery `dataset` используется как синоним `schema`.

Нужно ли создавать целевую схему перед запуском 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) для отладки любых ошибок.

### Создайте модель с помощью ИИ в dbt Wizard

Не хотите писать SQL вручную? [CLI dbt Wizard](https://docs.getdbt.tech/docs/dbt-ai/wizard-cli.md?section=qs-build-with-ai-cli) может создать ту же модель прямо из терминала, опираясь на фактическую схему и граф зависимостей вашего проекта. Но будьте осторожны: говорят, что этот волшебник умеет творить заклинания.

1. Установите CLI dbt Wizard:

### macOS/Linux

```shell
curl -fsSL https://public.cdn.getdbt.com/dbt-wizard/install/install-wizard.sh | sh
```

### Windows (PowerShell)

```powershell
irm https://public.cdn.getdbt.com/dbt-wizard/install/install-wizard.ps1 | iex
```

2. Запустите `wizard` в каталоге проекта, чтобы начать сеанс, а затем пройдите первоначальную настройку (если вы ещё этого не сделали).

[![Сеанс dbt Wizard в терминале](/img/docs/wizard-cli-intro.png?v=2 "Сеанс dbt Wizard в терминале")](#)Сеанс dbt Wizard в терминале

3. Введите запрос: «Создай модель customers, которая объединяет orders и customers и включает дату последнего заказа и общее количество заказов для каждого клиента».
4. Проверьте SQL, сгенерированный dbt Wizard, а затем примите его, чтобы сохранить модель.
5. Введите `dbt run`, чтобы построить её.

В любом случае вы получите одну и ту же работающую модель. Подробные инструкции по настройке см. в разделе [Локальное использование dbt Wizard](https://docs.getdbt.tech/docs/dbt-ai/wizard-cli.md).

## Измените способ материализации вашей модели

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

По умолчанию все создается как представление. Вы можете переопределить это на уровне директории, чтобы все в этой директории материализовалось по-другому.

1. Отредактируйте ваш файл `dbt_project.yml`.

   * Обновите имя вашего проекта на:

     dbt\_project.yml

     ```yaml
     name: 'jaffle_shop'
     ```

   * Настройте `jaffle_shop` так, чтобы всё внутри него материализовалось как таблица; и настройте `example` так, чтобы всё внутри него материализовалось как представление (view). Обновите конфигурацию `models` в YAML-файле проекта следующим образом:

     dbt\_project.yml

     ```yaml
     models:
       jaffle_shop:
         +materialized: table
         example:
           +materialized: view
     ```

   * Нажмите **Сохранить**.

2. Введите команду `dbt run`. Ваша модель `customers` теперь должна быть построена как таблица!

   к сведению

   Для этого dbt сначала должен был выполнить оператор `drop view` (или API вызов на BigQuery), затем оператор `create table as`.

3. Отредактируйте `models/customers.sql`, чтобы переопределить `dbt_project.yml` только для модели `customers`, добавив следующий фрагмент в начало, и нажмите **Сохранить**:

   models/customers.sql

   ```sql
   {{
     config(
       materialized='view'
     )
   }}

   with customers as (

       select
           id as customer_id
           ...

   )
   ```

4. Введите команду `dbt run`. Ваша модель `customers` теперь должна быть построена как представление.

   * Пользователям BigQuery необходимо выполнить `dbt run --full-refresh` вместо `dbt run`, чтобы полностью применить изменения материализации.

5. Введите команду `dbt run --full-refresh`, чтобы изменения вступили в силу в вашем хранилище данных.

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

Какие материализации доступны в 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.

Какую материализацию использовать для моей модели?

Начните с представлений (views), а затем измените модели на таблицы, когда это потребуется по причинам производительности (например, когда последующие запросы замедлились).

Ознакомьтесь с [документацией по материализациям](https://docs.getdbt.tech/docs/build/materializations.md) для получения советов о том, когда использовать каждую материализация.

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

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

* [теги](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), чтобы узнать больше.

## Удалите примерные модели

Теперь вы можете удалить файлы, которые dbt создал при инициализации проекта:

1. Удалите директорию `models/example/`.

2. Удалите ключ `example:` из вашего файла `dbt_project.yml`, а также любые конфигурации, которые перечислены под ним.

   dbt\_project.yml

   ```yaml
   # до
   models:
     jaffle_shop:
       +materialized: table
       example:
         +materialized: view
   ```

   dbt\_project.yml

   ```yaml
   # после
   models:
     jaffle_shop:
       +materialized: table
   ```

3. Сохраните изменения.

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

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

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

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

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

Я получил сообщение об ошибке "неиспользуемые конфигурации модели", что это значит?

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

Ознакомьтесь с этой [статьей](https://discourse.getdbt.com/t/faq-i-got-an-unused-model-configurations-error-message-what-does-this-mean/112), чтобы понять больше.

## Постройте модели на основе других моделей

Как лучшая практика в SQL, следует разделять логику, которая очищает ваши данные, от логики, которая трансформирует ваши данные. Вы уже начали делать это в существующем запросе, используя общие табличные выражения (CTE).

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

[![Граф, который мы хотим для нашего проекта dbt](/img/dbt-dag.png?v=2 "Граф, который мы хотим для нашего проекта dbt")](#)Граф, который мы хотим для нашего проекта dbt

1. Создайте новый SQL файл, `models/stg_customers.sql`, с SQL из CTE `customers` в нашем оригинальном запросе.
2. Создайте второй новый SQL файл, `models/stg_orders.sql`, с SQL из CTE `orders` в нашем оригинальном запросе.

### BigQuery

models/stg\_customers.sql

```sql
select
    id as customer_id,
    first_name,
    last_name

from `dbt-tutorial`.jaffle_shop.customers
```

models/stg\_orders.sql

```sql
select
    id as order_id,
    user_id as customer_id,
    order_date,
    status

from `dbt-tutorial`.jaffle_shop.orders
```

### Databricks

models/stg\_customers.sql

```sql
select
    id as customer_id,
    first_name,
    last_name

from jaffle_shop_customers
```

models/stg\_orders.sql

```sql
select
    id as order_id,
    user_id as customer_id,
    order_date,
    status

from jaffle_shop_orders
```

### Redshift

models/stg\_customers.sql

```sql
select
    id as customer_id,
    first_name,
    last_name

from jaffle_shop.customers
```

models/stg\_orders.sql

```sql
select
    id as order_id,
    user_id as customer_id,
    order_date,
    status

from jaffle_shop.orders
```

### Snowflake

models/stg\_customers.sql

```sql
select
    id as customer_id,
    first_name,
    last_name

from raw.jaffle_shop.customers
```

models/stg\_orders.sql

```sql
select
    id as order_id,
    user_id as customer_id,
    order_date,
    status

from raw.jaffle_shop.orders
```

3. Отредактируйте SQL в вашем файле `models/customers.sql` следующим образом:

models/customers.sql

```sql
with customers as (

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

),

orders as (

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

),

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 orders

    group by 1

),

final as (

    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 customers

    left join customer_orders using (customer_id)

)

select * from final
```

4. Выполните `dbt run`.

На этот раз, когда вы выполнили `dbt run`, были созданы отдельные представления/таблицы для `stg_customers`, `stg_orders` и `customers`. dbt определил порядок выполнения этих моделей. Поскольку `customers` зависит от `stg_customers` и `stg_orders`, dbt строит `customers` последним. Вам не нужно явно определять эти зависимости.

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

Как запустить одну модель за раз?

Чтобы запустить одну модель, используйте флаг `--select` (или флаг `-s`), указав имя модели:

```shell
$ dbt run --select customers
```

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

Должны ли имена ресурсов, используемых в 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 Labs) [структурируем наши dbt проекты](https://docs.getdbt.tech/best-practices/how-we-structure/1-guide-overview.md).

### Следующие шаги

Прежде чем двигаться дальше после создания ваших первых моделей, внесите изменения и посмотрите, как это повлияет на ваши результаты:

* Напишите некорректный SQL, чтобы вызвать ошибку — сможете ли вы отладить ошибку?

* Запустите только одну модель за раз. Для получения дополнительной информации смотрите [Обзор синтаксиса](https://docs.getdbt.tech/reference/node-selection/syntax.md).

* Сгруппируйте ваши модели с префиксом `stg_` в подкаталог `staging`. Например, `models/staging/stg_customers.sql`.

  * Настройте ваши `staging` модели как представления (views).
  * Запустите только `staging` модели.

Вы также можете исследовать:

* Каталог `target`, чтобы просмотреть весь скомпилированный SQL. В каталоге `run` находятся выполняемые операторы create or replace table — это операторы select, обёрнутые в соответствующий DDL.
* Файл `logs`, чтобы посмотреть, как dbt записывает в журнал все действия, происходящие в вашем проекте. В нём отображаются выполняемые операторы select и другие сообщения журнала, выводимые при запуске dbt.

## Добавьте тесты к вашим моделям

Добавление [data tests](https://docs.getdbt.tech/docs/build/data-tests.md) в проект помогает убедиться, что ваши модели работают корректно.

Чтобы добавить data tests в проект:

1. Создайте новый YAML-файл в директории `models`, назвав его `models/schema.yml`.

2. Добавьте в файл следующее содержимое:

   models/schema.yml

   ```yaml
   version: 2

   models:
     - name: customers
       columns:
         - name: customer_id
           data_tests:
             - unique
             - not_null

     - name: stg_customers
       columns:
         - name: customer_id
           data_tests:
             - unique
             - not_null

     - name: stg_orders
       columns:
         - name: order_id
           data_tests:
             - unique
             - not_null
         - name: status
           data_tests:
             - accepted_values:
                 arguments: # available in v1.10.5 and higher. Older versions can set the <argument_name> as the top-level property.
                   values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
         - name: customer_id
           data_tests:
             - not_null
             - relationships:
                 arguments:
                   to: ref('stg_customers')
                   field: customer_id
   ```

3. Запустите `dbt test` и убедитесь, что все ваши тесты прошли успешно.

Когда вы запускаете `dbt test`, dbt проходит по вашим YAML-файлам и создает запрос для каждого теста. Каждый запрос вернет количество записей, которые не прошли тест. Если это число равно 0, то тест считается успешным.

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

Какие тесты доступны для использования в dbt? Могу ли я добавить свои собственные тесты?

«Из коробки» dbt поставляется со следующими тестами данных:

* `unique`
* `not_null`
* `accepted_values`
* `relationships` (например, ссылочная целостность)

Вы также можете написать собственные [пользовательские универсальные тесты](https://docs.getdbt.tech/docs/build/data-tests.md#generic-data-tests).

Дополнительные универсальные тесты с открытым исходным кодом доступны в [пакете dbt-utils](https://github.com/dbt-labs/dbt-utils#generic-tests). Ознакомьтесь с документацией по [пакетам](https://docs.getdbt.tech/docs/build/packages.md), чтобы узнать, как использовать эти тесты в вашем проекте.

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

Запуск тестов для одной модели очень похож на запуск самой модели: используйте флаг `--select` (или флаг `-s`), за которым следует имя модели:

```shell
dbt test --select customers
```

Ознакомьтесь с [документацией по синтаксису выбора моделей](https://docs.getdbt.tech/reference/node-selection/syntax.md) для полного синтаксиса, и [примерами выбора тестов](https://docs.getdbt.tech/reference/node-selection/test-selection-examples.md) в частности.

Один из моих тестов не прошел, как я могу его отладить?

Чтобы отладить неудачный тест, найдите SQL, который выполнил dbt, следующим образом:

* dbt:

  * В результатах тестирования нажмите на тест, завершившийся с ошибкой, а затем выберите «Details».

* dbt v1:

  * Откройте файл по пути, указанному в сообщении об ошибке.
  * Перейдите в каталог `target/compiled/schema_tests`, где находятся все скомпилированные SQL-запросы тестов.

Скопируйте SQL-код в редактор запросов (в dbt его можно вставить в новый `Statement`) и выполните запрос, чтобы найти записи, не прошедшие тест.

Должен ли мой файл с тестами называться \`schema.yml\`?

Нет! Вы можете назвать этот файл как угодно (включая `whatever_you_want.yml`), при условии, что:

* Файл находится в вашем каталоге `models/`¹
* Файл имеет расширение `.yml`

Посмотрите [документацию](https://docs.getdbt.tech/reference/configs-and-properties.md) для получения дополнительной информации.

¹Если вы объявляете свойства для seeds, snapshots или macros, вы также можете разместить этот файл в соответствующем каталоге — `seeds/`, `snapshots/` и `macros/` соответственно.

Почему файлы YAML для моделей и источников всегда начинаются с \`version: 2\`?

Когда‑то структура этих файлов `.yml` была совсем другой (привет всем, кто пользовался dbt в те времена!). Добавление `version: 2` позволило нам сделать эту структуру более расширяемой.

Начиная с [dbt v1.5](<https://docs.getdbt.tech/docs/dbt-versions/dbt-upgrade/Older versions/upgrading-to-v1.5/.md#quick-hits>), ключ `version:` верхнего уровня необязателен во всех YAML-файлах ресурсов. Если он указан, поддерживается только значение `version: 2`.

Также, начиная с версии 1.5, и [`config-version: 2`](https://docs.getdbt.tech/reference/project-configs/config-version.md), и ключ верхнего уровня `version:` в файле `dbt_project.yml` являются необязательными.

В настоящее время ресурсные YAML‑файлы не требуют наличия этой настройки. Если она указана, мы поддерживаем только `version: 2`. Хотя мы не ожидаем в ближайшее время обновлять YAML‑файлы до `version: 3`, наличие этой конфигурации упростит для нас внедрение новых структур в будущем.

Какие тесты данных стоит добавить в проект?

Мы рекомендуем, чтобы у каждой модели был data test на первичный ключ, то есть на колонку, которая является `unique` и `not_null`.

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

В продвинутых проектах dbt мы рекомендуем использовать [sources](https://docs.getdbt.tech/docs/build/sources.md) и запускать эти тесты целостности данных источника против источников, а не моделей.

Когда следует запускать data tests?

Вам следует запускать data tests каждый раз, когда вы пишете новый код (чтобы убедиться, что изменения в SQL не сломали существующие модели), а также каждый раз, когда вы запускаете трансформации в production (чтобы убедиться, что ваши предположения о исходных данных по‑прежнему верны).

### Следующие шаги

Прежде чем двигаться дальше от тестирования, внесите изменения и посмотрите, как это повлияет на ваши результаты:

* Напишите тест, который не пройдет, например, исключите один из статусов заказа из списка `accepted_values`. Как выглядит неудачный тест? Можете ли вы отладить ошибку?
* Запустите тесты только для одной модели. Если вы сгруппировали свои модели с префиксом `stg_` в отдельную директорию, попробуйте запустить тесты для всех моделей в этой директории.
* Используйте [блок документации](https://docs.getdbt.tech/docs/build/documentation.md#using-docs-blocks), чтобы добавить описание в формате Markdown к модели.

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

[Документация](https://docs.getdbt.tech/docs/build/documentation.md) позволяет подробно описывать модели и делиться этими сведениями с командой. Добавим описания в проект:

Обновите файл `models/schema.yml`, добавив описания, например приведённые ниже.

models/schema.yml

```yaml
version: 2

models:
  - name: customers
    description: Одна запись на каждого клиента
    columns:
      - name: customer_id
        description: Первичный ключ
        data_tests:
          - unique
          - not_null
      - name: first_order_date
        description: NULL, если клиент ещё не сделал ни одного заказа.

  - name: stg_customers
    description: Эта модель очищает данные о клиентах
    columns:
      - name: customer_id
        description: Первичный ключ
        data_tests:
          - unique
          - not_null

  - name: stg_orders
    description: Эта модель очищает данные о заказах
    columns:
      - name: order_id
        description: Первичный ключ
        data_tests:
          - unique
          - not_null
      - name: status
        data_tests:
          - accepted_values:
              arguments: # доступно в версии v1.10.5 и выше. В более ранних версиях <argument_name> можно задать как свойство верхнего уровня.
                values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
      - name: customer_id
        data_tests:
          - not_null
          - relationships:
              arguments:
                to: ref('stg_customers')
                field: customer_id
```

1. Выполните `dbt docs generate`, чтобы скомпилировать артефакты, необходимые для статического сайта документации вашего проекта.
2. Выполните `dbt docs serve`, чтобы открыть документацию на локальном веб-сайте.

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

Как писать развернутые объяснения в описаниях?

Если для описания модели вам нужно больше одного предложения, вы можете:

1. Разбить описание на несколько строк с помощью `>`. Переносы строк внутри описания удаляются, при этом можно использовать Markdown. Этот способ рекомендуется для простых описаний из одного абзаца:

```yml
models:
  - name: customers
    description: >
      Lorem ipsum **dolor** sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
      quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
      consequat.
```

2. Разбейте описание на несколько строк с помощью `|`. Внутренние переносы строк сохраняются, и можно использовать Markdown. Этот способ рекомендуется для более сложных описаний:

```yml
models:
  - name: customers
    description: |
      ### Lorem ipsum

      * dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      * tempor incididunt ut labore et dolore magna aliqua.
```

3. Использовать [блок docs](https://docs.getdbt.tech/docs/build/documentation.md#using-docs-blocks), чтобы написать описание в отдельном Markdown файле.

Как получить доступ к документации в dbt Catalog?

Если вы используете dbt для развертывания проекта и у вас [тарифный план Starter, Enterprise или Enterprise+](https://www.getdbt.com/pricing/), вы можете использовать Catalog для просмотра [ресурсов](https://docs.getdbt.tech/docs/build/projects.md) проекта (таких как модели, тесты и метрики) и их происхождения и связей, чтобы лучше понимать текущее состояние проекта в промышленной среде.

Чтобы открыть Catalog в dbt, нажмите ссылку **Catalog** в меню навигации. Пользователи с доступом только для чтения могут просматривать документацию вашего проекта — сведения о доступности лицензий в зависимости от тарифного плана см. на странице [тарифов dbt](https://www.getdbt.com/pricing).

Пользователи тарифного плана Developer в dbt и пользователи dbt v1 могут использовать [dbt Docs](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md?version=1.12#dbt-docs): этот инструмент создает базовую документацию, но не обеспечивает такую же скорость работы, объем метаданных и наглядность, как Catalog.

## Создайте коммит с обновлёнными изменениями

Вам нужно зафиксировать изменения, которые вы внесли в проект, чтобы репозиторий содержал ваш последний код.

1. Добавьте все изменения в git: `git add -A`
2. Создайте коммит с изменениями: `git commit -m "Add customers model, tests, docs"`
3. Отправьте изменения в свой репозиторий: `git push -u origin add-customers-model`
4. Перейдите в свой репозиторий и откройте пул-реквест, чтобы объединить код с веткой master.

## Запланируйте задание

Мы рекомендуем использовать dbt platform как самый простой и надёжный способ [запускать задания](https://docs.getdbt.tech/docs/deploy/deployments.md) и автоматизировать ваш проект dbt в промышленной среде.

Для получения дополнительной информации о том, как начать, обратитесь к [созданию и планированию заданий](https://docs.getdbt.tech/docs/deploy/deploy-jobs.md#create-and-schedule-jobs).

[![Обзор запуска задания dbt, включая сведения о запуске, тип триггера, SHA коммита, имя среды, подробные шаги выполнения, журналы и многое другое.](/img/docs/dbt-platform/deployment/run-overview.png?v=2 "Обзор запуска задания dbt, включая сведения о запуске, тип триггера, SHA коммита, имя среды, подробные шаги выполнения, журналы и многое другое.")](#)Обзор запуска задания dbt, включая сведения о запуске, тип триггера, SHA коммита, имя среды, подробные шаги выполнения, журналы и многое другое.

Чтобы самостоятельно настроить расписание заданий с помощью оркестратора, например Airflow, обратитесь к статье в блоге [dbt и Airflow](https://docs.getdbt.tech/blog/dbt-airflow-spiritual-alignment).

Подключите свой ИИ-инструмент к этому проекту

Теперь, когда ваш проект настроен и работает, подключите к нему свой ИИ-инструмент (например, Claude или ChatGPT) через [dbt MCP server](https://docs.getdbt.tech/docs/dbt-ai/about-mcp.md?section=qs-connect-ai), чтобы задавать вопросы о моделях на естественном языке. Описания, тесты и семантические модели помогут сделать его ответы ещё лучше.
