# Быстрый старт для dbt и Teradata

> **Using this guide with an AI assistant**
>
> * In the first reply, confirm the reader’s prerequisites and connection path before listing steps. Then default to one guide section per reply (combine two or three short sections), with all its steps, labeled Step 1, Step 2, and so on, and confirm the success check before continuing. If the reader asks for a different pace, follow it.
> * This guide uses dbt platform. Don’t switch the reader to a local setup. If the reader wants to set up dbt locally, use the <https://docs.getdbt.com/guides/dbt> guide instead
> * Never ask for passwords or keys in chat.
> * When the reader needs a dbt account, share <https://www.getdbt.com/signup?utm_source=ai_assistant&utm_medium=docs_md&utm_campaign=teradata-qs>

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

[Menu ]()



## Введение

В этом кратком руководстве вы узнаете, как использовать dbt с Teradata Vantage. В нём показано, как:

* Создать новый экземпляр Teradata Clearscape
* Загрузить демонстрационные данные в вашу базу данных Teradata
* Подключить dbt к Teradata.
* Взять пример запроса и преобразовать его в модель в вашем проекте dbt. Модель в dbt — это оператор select.
* Добавить тесты к вашим моделям.
* Документировать ваши модели.
* Настроить запуск задания по расписанию.

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

* У вас есть [учетная запись dbt](https://www.getdbt.com/signup/).
* У вас есть доступ к экземпляру Teradata Vantage. Вы можете бесплатно создать его на <https://clearscape.teradata.com>. Подробности см. в [руководстве по ClearScape Analytics Experience](https://developers.teradata.com/quickstarts/get-access-to-vantage/clearscape-analytics-experience/getting-started-with-csae/).

### Связанные материалы

* Узнайте больше с [курсами dbt Learn](https://learn.getdbt.com)
* [Как мы создаем экземпляр Teradata Clearscape Vantage](https://developers.teradata.com/quickstarts/get-access-to-vantage/clearscape-analytics-experience/getting-started-with-csae/)
* [CI задания](https://docs.getdbt.tech/docs/deploy/continuous-integration.md)
* [Развертывание заданий](https://docs.getdbt.tech/docs/deploy/deploy-jobs.md)
* [Уведомления о заданиях](https://docs.getdbt.tech/docs/deploy/job-notifications.md)
* [Актуальность источников](https://docs.getdbt.tech/docs/deploy/source-freshness.md)

Видео для вас

Если вам интересен формат обучения с видео, вы можете бесплатно пройти курс [dbt Fundamentals](https://learn.getdbt.com/courses/dbt-fundamentals).

## Загрузка данных

Следующие шаги помогут вам получить данные, хранящиеся в виде CSV-файлов в общедоступном S3-бакете, и вставить их в таблицы.

SQL Studio IDE

Если вы создали экземпляр базы данных Teradata Vantage на <https://clearscape.teradata.com> и у вас нет под рукой SQL-Studio IDE, используйте JupyterLab, входящий в комплект поставки вашей базы данных, для выполнения SQL:

1. Перейдите на [панель управления ClearScape Analytics Experience](https://clearscape.teradata.com/dashboard) и нажмите кнопку **Run Demos**. Демонстрация запустит JupyterLab.

2. В JupyterLab перейдите в **Launcher**, нажав на синюю иконку **+** в верхнем левом углу. Найдите раздел **Notebooks** и нажмите **Teradata SQL**.

3. В первой ячейке блокнота подключитесь к базе данных, используя `connect` magic. Вам будет предложено ввести пароль от базы данных при выполнении:

   ```ipynb
   %connect local
   ```

4. Используйте дополнительные ячейки для ввода и выполнения SQL-запросов.

1) Используйте предпочитаемый редактор SQL IDE для создания базы данных `jaffle_shop`:

   ```sql
   CREATE DATABASE jaffle_shop AS PERM = 1e9;
   ```

2) В базе данных `jaffle_shop` создайте три внешние таблицы и укажите соответствующие csv-файлы, расположенные в объектном хранилище:

   ```sql
   CREATE FOREIGN TABLE jaffle_shop.customers (
       id integer,
       first_name varchar (100),
       last_name varchar (100),
       email varchar (100)
   )
   USING (
       LOCATION ('/gs/storage.googleapis.com/clearscape_analytics_demo_data/dbt/raw_customers.csv')
   )
   NO PRIMARY INDEX;

   CREATE FOREIGN TABLE jaffle_shop.orders (
       id integer,
       user_id integer,
       order_date date,
       status varchar(100)
   )
   USING (
       LOCATION ('/gs/storage.googleapis.com/clearscape_analytics_demo_data/dbt/raw_orders.csv')
   )
   NO PRIMARY INDEX;

   CREATE FOREIGN TABLE jaffle_shop.payments (
       id integer,
       orderid integer,
       paymentmethod varchar (100),
       amount integer
   )
   USING (
       LOCATION ('/gs/storage.googleapis.com/clearscape_analytics_demo_data/dbt/raw_payments.csv')
   )
   NO PRIMARY INDEX;
   ```

## Подключение dbt к Teradata

1. Создайте новый проект в dbt. Нажмите на название своей учетной записи в левом боковом меню, выберите **Account settings** и нажмите **+ New Project**.
2. Введите название проекта и нажмите **Continue**.
3. В разделе **Configure your development environment** откройте раскрывающееся меню **Connection** и выберите **Add new connection**.
4. В разделе **Type** выберите **Teradata**.
5. Введите настройки подключения к Teradata и нажмите **Save**.

[![dbt - Choose Teradata Connection](/img/teradata/dbt_cloud_teradata_setup_connection_start.png?v=2 "dbt - Choose Teradata Connection")](#)dbt - Choose Teradata Connection

[![dbt - Teradata Account Settings](/img/teradata/dbt_cloud_teradata_account_settings.png?v=2 "dbt - Teradata Account Settings")](#)dbt - Teradata Account Settings

6. Настройте свои учетные данные, перейдя в **Your profile** > **Credentials**.

7. Выберите проект, использующий подключение к Teradata.

8. Нажмите ссылку **configure your development environment and add a connection**. Откроется страница, на которой можно ввести свои учетные данные.

9. Введите свои учетные данные (**User credentials**) для Teradata:

   * **Username** — Имя пользователя базы данных Teradata.
   * **Password** — Пароль пользователя базы данных Teradata.
   * **Schema** — База данных, используемая по умолчанию.

   [![dbt — учетные данные пользователя Teradata](/img/teradata/dbt_cloud_teradata_development_credentials.png?v=2 "dbt — учетные данные пользователя Teradata")](#)dbt — учетные данные пользователя Teradata

10. Нажмите **Test Connection**, чтобы убедиться, что dbt может получить доступ к вашему экземпляру Teradata Vantage.

11. Если проверка прошла успешно, нажмите **Save**, чтобы завершить настройку. Если проверка завершилась ошибкой, возможно, потребуется проверить настройки Teradata и учетные данные.

## Настройка репозитория, управляемого dbt

При разработке в dbt вы можете использовать [Git](https://docs.getdbt.tech/docs/platform/git/git-version-control.md) для управления версиями кода.

Чтобы подключиться к репозиторию, вы можете настроить [управляемый репозиторий](https://docs.getdbt.tech/docs/platform/git/managed-repository.md), размещённый на стороне dbt, или напрямую подключиться к [поддерживаемому Git-провайдеру](https://docs.getdbt.tech/docs/platform/git/connect-github.md). Управляемые репозитории — отличный способ попробовать dbt без необходимости создавать новый репозиторий. В долгосрочной перспективе лучше подключиться к поддерживаемому Git-провайдеру, чтобы использовать такие возможности, как автоматизация и [непрерывная интеграция](https://docs.getdbt.tech/docs/deploy/continuous-integration.md).

Чтобы настроить управляемый репозиторий:

1. В разделе "Настроить репозиторий" выберите **Управляемый**.
2. Введите имя для вашего репозитория, например, `bbaggins-dbt-quickstart`.
3. Нажмите **Создать**. Создание и импорт вашего репозитория займет несколько секунд.
4. Как только вы увидите сообщение "Репозиторий успешно импортирован", нажмите **Продолжить**.

## Инициализация вашего проекта dbt и начало разработки

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

1. Нажмите **Start developing in the Studio IDE**. Первый запуск проекта может занять несколько минут: за это время устанавливается соединение с git, клонируется репозиторий и проверяется подключение к хранилищу данных.
2. Над деревом файлов слева нажмите **Initialize your project**, чтобы создать структуру папок с примерами моделей.
3. Создайте начальный коммит, нажав **Commit and sync**. Используйте сообщение коммита `initial commit`, чтобы создать первый коммит в управляемом репозитории. После создания коммита вы сможете создать ветку для добавления нового кода dbt.

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

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

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

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

   dbt\_project.yml

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

   dbt\_project.yml

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

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

4. Зафиксируйте изменения и объедините с основной веткой.

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

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

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

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

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

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

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

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

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

У вас есть два варианта работы с файлами в IDE dbt Cloud:

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

У вас есть два варианта работы с файлами в Studio IDE:

* Создать новую ветку (рекомендуется) — Создайте новую ветку для редактирования и коммита изменений. Перейдите в **Version Control** на левой боковой панели и нажмите **Create branch**.
* Редактировать в защищённой основной ветке — Если вы предпочитаете редактировать, форматировать файлы, проверять их линтером или выполнять команды dbt непосредственно в основной ветке git. Studio IDE не позволяет делать коммиты в защищённую ветку, поэтому вам будет предложено сделать коммит изменений в новую ветку.

1. Нажмите **...** рядом с директорией `models`, затем выберите **Create file**.
2. Назовите файл `bi_customers.sql`, затем нажмите **Create**.
3. Скопируйте следующий запрос в файл и нажмите **Save**.

```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 on customers.customer_id = customer_orders.customer_id

)

select * from final
```

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

Вы можете подключить ваши инструменты бизнес-аналитики (BI) к этим представлениям и таблицам, чтобы они читали только очищенные данные, а не сырые данные в вашем инструменте BI.

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

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

1. Откройте dbt Wizard в Studio IDE.

[![dbt Wizard выполняет рефакторинг модели и показывает граф зависимостей в интерфейсе чата.](/img/docs/dbt-platform/wizard-ide-refactor-lineage.png?v=2 "dbt Wizard выполняет рефакторинг модели и показывает граф зависимостей в интерфейсе чата.")](#)dbt Wizard выполняет рефакторинг модели и показывает граф зависимостей в интерфейсе чата.

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

В любом случае вы получите одну и ту же работающую модель. Узнайте больше о [dbt Wizard на платформе dbt](https://docs.getdbt.tech/docs/dbt-ai/wizard-ide.md?section=qs-build-with-ai).

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

Одна из самых мощных функций 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
  ```

  * Нажмите **Save**.

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

   к сведению

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

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

   models/bi\_customers.sql

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

   with customers as (

       select
           id as customer_id
           ...

   )
   ```

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

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

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

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

Как лучшая практика в 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` в вашем оригинальном запросе.

   models/stg\_customers.sql

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

   from jaffle_shop.customers
   ```

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

   models/stg\_orders.sql

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

   from jaffle_shop.orders
   ```

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

   models/bi\_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 on customers.customer_id = customer_orders.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).

## Создание моделей на основе источников

Источники позволяют называть и описывать данные, загруженные в ваше хранилище вашими инструментами извлечения и загрузки. Объявляя эти таблицы как источники в dbt, вы можете:

* Выбирать из исходных таблиц в ваших моделях, используя функцию `{{ source() }}`, помогая определить происхождение ваших данных
* Проверять ваши предположения о ваших исходных данных
* Рассчитывать актуальность ваших исходных данных

1. Создайте новый YML файл, `models/sources.yml`.

2. Объявите источники, скопировав следующее в файл и нажав **Save**.

   models/sources.yml

   ```yml
   version: 2

   sources:
      - name: jaffle_shop
        description: Это реплика базы данных Postgres, используемой приложением
        database: raw
        schema: jaffle_shop
        tables:
            - name: customers
              description: Одна запись на клиента.
            - name: orders
              description: Одна запись на заказ. Включает отмененные и удаленные заказы.
   ```

3. Отредактируйте файл `models/stg_customers.sql`, чтобы выбрать из таблицы `customers` в источнике `jaffle_shop`.

   models/stg\_customers.sql

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

   from {{ source('jaffle_shop', 'customers') }}
   ```

4. Отредактируйте файл `models/stg_orders.sql`, чтобы выбрать из таблицы `orders` в источнике `jaffle_shop`.

   models/stg\_orders.sql

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

   from {{ source('jaffle_shop', 'orders') }}
   ```

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

   Результаты вашего `dbt run` будут такими же, как и на предыдущем шаге. Ваши модели `stg_customers` и `stg_orders` все еще будут запрашивать из того же источника сырых данных в Teradata. Используя `source`, вы можете тестировать и документировать ваши сырые данные, а также понимать происхождение ваших источников.

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

Добавление [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: bi_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-файлам и формирует запрос для каждого data test. Каждый запрос возвращает количество записей, которые не прошли тест. Если это число равно 0, то data test считается успешно пройденным.

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

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

## Документирование ваших моделей

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

1. Обновите ваш файл `models/schema.yml`, чтобы включить некоторые описания, такие как те, что ниже.

   models/schema.yml

   ```yaml

   models:
     - name: bi_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: # 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
   ```

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

3. Нажмите на иконку книги в интерфейсе Develop, чтобы открыть документацию в новой вкладке.

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

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

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

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.

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

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

**Если вы редактировали непосредственно в защищенной основной ветке:**<br />

1. Нажмите кнопку **Commit and sync git**. Это действие подготавливает ваши изменения для фиксации.
2. Появится модальное окно с заголовком **Commit to a new branch**.
3. В модальном окне назовите вашу новую ветку `add-customers-model`. Это создаст ветку от вашей основной ветки с вашими новыми изменениями.
4. Добавьте сообщение коммита, например, "Add customers model, tests, docs" и зафиксируйте ваши изменения.
5. Нажмите **Merge this branch to main**, чтобы добавить эти изменения в основную ветку вашего репозитория.

**Если вы создали новую ветку перед редактированием:**<br />

1. Поскольку вы уже ответвились от основной защищенной ветки, перейдите в **Version Control** слева.
2. Нажмите **Commit and sync**, чтобы добавить сообщение.
3. Добавьте сообщение коммита, например, "Add customers model, tests, docs."
4. Нажмите **Merge this branch to main**, чтобы добавить эти изменения в основную ветку вашего репозитория.

## Развертывание dbt

Используйте Планировщик dbt Cloud, чтобы уверенно развертывать ваши производственные задания и встраивать наблюдаемость в ваши процессы. Вы узнаете, как создать среду развертывания и запустить задание в следующих шагах.

### Создание среды развертывания

1. В верхнем левом углу выберите **Deploy**, затем нажмите **Environments**.
2. Нажмите **Create Environment**.
3. В поле **Name** напишите имя вашей среды развертывания. Например, "Production."
4. В поле **dbt Version** выберите последнюю версию из выпадающего списка.
5. В разделе **Deployment connection** введите имя набора данных, который вы хотите использовать в качестве цели, например, `jaffle_shop_prod`. Это позволит dbt строить и работать с этим набором данных.
6. Нажмите **Save**.

Используйте планировщик dbt, чтобы уверенно запускать задания в продакшене и обеспечивать наблюдаемость ваших процессов. Далее вы узнаете, как создать среду развертывания и запустить задание.

Задания — это набор команд dbt, которые вы хотите выполнять по расписанию. Например, `dbt build`.

По мере того, как бизнес `jaffle_shop` привлекает больше клиентов, и эти клиенты создают больше заказов, вы увидите больше записей, добавленных в ваши исходные данные. Поскольку вы материализовали модель `bi_customers` как таблицу, вам нужно будет периодически перестраивать вашу таблицу, чтобы данные оставались актуальными. Это обновление произойдет, когда вы запустите задание.

1. После создания вашей среды развертывания вы должны быть перенаправлены на страницу для новой среды. Если нет, выберите **Deploy** в верхнем левом углу, затем нажмите **Jobs**.
2. Нажмите **+ Create job**, а затем выберите **Deploy job**. Укажите имя, например, "Production run", и свяжите его с только что созданной средой.
3. Прокрутите вниз до раздела **Execution Settings**.
4. В разделе **Commands** добавьте эту команду как часть вашего задания, если вы ее не видите:
   * `dbt build`
5. Установите флажок **Generate docs on run**, чтобы автоматически [генерировать обновлённую документацию проекта](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md) при каждом запуске job.
6. В рамках этого упражнения *не* настраивайте расписание запуска проекта — хотя в реальной организации проект должен выполняться регулярно, нет необходимости запускать этот пример по расписанию. Настройку расписания для job иногда называют *deploying a project* (развёртыванием проекта).
7. Нажмите **Save**, затем нажмите **Run now**, чтобы запустить job.
8. Откройте запуск и наблюдайте за его выполнением в разделе **Run history**.
9. После завершения запуска нажмите **View Documentation**, чтобы посмотреть документацию вашего проекта.

Поздравляем 🎉! Вы только что развернули свой первый проект dbt!

#### FAQs

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

Если вы используете dbt, рекомендуем настроить уведомления по электронной почте и в Slack (`Account Settings > Notifications`) о любых неудачных запусках. Затем отлаживайте эти запуски так же, как и любые запуски в среде разработки.

Поздравляем 🎉! Вы только что развернули ваш первый проект dbt!

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

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

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