Быстрый старт для dbt Core с ручной установкой

dbt Core

Quickstart

Beginner

Menu

Введение

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

Если вы хотите редактировать файлы и запускать проекты, используя веб-ориентированную интегрированную среду разработки dbt (IDE), обратитесь к быстрым стартам dbt Cloud. Вы также можете разрабатывать и выполнять команды dbt, используя dbt Cloud CLI — командную строку, поддерживаемую dbt Cloud.

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

• Чтобы использовать dbt Core, важно знать некоторые основы работы с Терминалом. В частности, вы должны понимать команды cd, ls и pwd, чтобы легко перемещаться по структуре каталогов вашего компьютера.
• Установите dbt Core, следуя инструкциям по установке для вашей операционной системы.
• Выполните соответствующие шаги по настройке и загрузке данных в серии Quickstart для dbt Cloud. Например, для BigQuery выполните Настройка (в BigQuery) и Загрузка данных (BigQuery).
• Создайте учетную запись GitHub, если у вас ее еще нет.

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

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

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

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

1. Создайте новый репозиторий GitHub с именем dbt-tutorial.
2. Выберите Public, чтобы репозиторий можно было поделиться с другими. Вы всегда можете сделать его приватным позже.
3. Оставьте значения по умолчанию для всех остальных настроек.
4. Нажмите Create repository.
5. Сохраните команды из раздела "…or create a new repository on the command line", чтобы использовать их позже в Commit your changes.

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

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

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

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

dbt --version

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

dbt init jaffle_shop

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

cd jaffle_shop

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

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

5. Используйте текстовый редактор, такой как Atom или VSCode, чтобы открыть директорию проекта, которую вы создали на предыдущих шагах, и которую мы назвали jaffle_shop. Содержимое включает папки и файлы .sql и .yml, сгенерированные командой init.

Стартовый проект в текстовом редакторе

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

dbt_project.yml

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

...

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

...

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

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

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

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

profiles.yml

jaffle_shop: # это должно совпадать с профилем в вашем файле dbt_project.yml
    target: dev
    outputs:
        dev:
            type: bigquery
            method: service-account
            keyfile: /Users/BBaggins/.dbt/dbt-tutorial-project-331118.json # замените это на полный путь к вашему ключевому файлу
            project: grand-highway-265418 # Замените это на ваш project id
            dataset: dbt_bbagins # Замените это на dbt_ваше_имя, например, dbt_bilbo
            threads: 1
            timeout_seconds: 300
            location: US
            priority: interactive

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

$ dbt debug
> Connection test: OK connection ok

Успешная команда dbt debug

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

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

Структура профиля выглядит по-разному для каждого хранилища. Ознакомьтесь со страницей Поддерживаемые платформы данных и перейдите в раздел Profile Setup для вашего хранилища.

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

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

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

Обычно мы используем название компании для имени профиля, а затем используем цели (targets) для различения между dev и prod. Ознакомьтесь с документацией о средах в dbt Core для получения дополнительной информации.

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

Мы обычно используем цели для различения разработческих и производственных запусков dbt, называя их соответственно dev и prod. Ознакомьтесь с документацией по управлению средами в dbt Core для получения дополнительной информации.

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

Да! Ознакомьтесь с документацией по переменным окружения для получения дополнительной информации.

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

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

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

dbt run

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

Успешная команда dbt run

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

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

1. Свяжите репозиторий GitHub, который вы создали, с вашим проектом dbt, выполнив следующие команды в Терминале. Убедитесь, что вы используете правильный URL git для вашего репозитория, который вы должны были сохранить на шаге 5 в Создание репозитория.

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, чтобы убедиться, что ваши новые файлы были добавлены.

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

Теперь, когда вы настроили ваш примерный проект, вы можете перейти к интересной части — созданию моделей! В следующих шагах вы возьмете пример запроса и превратите его в модель в вашем проекте dbt.

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

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

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

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

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

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

BigQuery

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

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

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

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 Core CLI

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

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

Как увидеть SQL, который выполняет dbt?

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

• dbt Cloud:
  • В выводе выполнения нажмите на имя модели, а затем выберите "Details"
• dbt Core:
  • Директория target/compiled/ для скомпилированных select выражений
  • Директория target/run/ для скомпилированных create выражений
  • Файл logs/dbt.log для подробного логирования.

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

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

• Если вы разрабатываете в dbt Cloud, эти параметры устанавливаются для каждого пользователя при первом использовании среды разработки.
• Если вы разрабатываете с dbt Core, это параметр schema: в вашем файле profiles.yml.

Если вы хотите распределить ваши модели по нескольким схемам, ознакомьтесь с документацией по использованию пользовательских схем.

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

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

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

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

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

Реализация этого процесса варьируется в зависимости от каждого хранилища данных, проверьте логи, чтобы увидеть, какой SQL выполняет dbt.

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

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

$ dbt run --select customers
Running with dbt=0.15.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 для отладки любых ошибок.

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

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

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

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

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

     dbt_project.yml

     name: 'jaffle_shop'

   • Настройте jaffle_shop так, чтобы все в нем материализовалось как таблица; и настройте example так, чтобы все в нем материализовалось как представление. Обновите блок конфигурации models следующим образом:

     dbt_project.yml

     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

   {{
     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. Ознакомьтесь с документацией по материализациям для получения дополнительной информации о каждом из этих вариантов.

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

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

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

Ознакомьтесь с документацией по материализациям для получения советов о том, когда использовать каждую .

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

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

• теги для поддержки легкой категоризации и выбора графа
• пользовательские схемы для разделения ваших моделей по нескольким схемам
• алиасы, если имя вашего / должно отличаться от имени файла
• Фрагменты SQL, которые выполняются в начале или в конце модели, известные как хуки
• Конфигурации, специфичные для хранилища, для повышения производительности (например, ключи sort и dist на Redshift, partitions на BigQuery)

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

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

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

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

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

   dbt_project.yml

   # до
   models:
     jaffle_shop:
       +materialized: table
       example:
         +materialized: view
   dbt_project.yml

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

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

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

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

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

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

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

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

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

Ознакомьтесь с этой статьей, чтобы понять больше.

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

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

Теперь вы можете поэкспериментировать, разделив логику на отдельные модели и используя функцию ref для построения моделей на основе других моделей:

Граф, который мы хотим для нашего проекта dbt

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

BigQuery

models/stg_customers.sql

select
    id as customer_id,
    first_name,
    last_name

from `dbt-tutorial`.jaffle_shop.customers

models/stg_orders.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

select
    id as customer_id,
    first_name,
    last_name

from jaffle_shop_customers

models/stg_orders.sql

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

from jaffle_shop_orders

Redshift

models/stg_customers.sql

select
    id as customer_id,
    first_name,
    last_name

from jaffle_shop.customers

models/stg_orders.sql

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

from jaffle_shop.orders

Snowflake

models/stg_customers.sql

select
    id as customer_id,
    first_name,
    last_name

from raw.jaffle_shop.customers

models/stg_orders.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

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), указав имя модели:

$ dbt run --select customers

Ознакомьтесь с документацией по синтаксису выбора моделей для получения информации о других операторах и примерах.

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

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

Ресурс в одном проекте может иметь то же имя, что и ресурс в другом проекте (установленном как зависимость). dbt использует имя проекта для уникальной идентификации каждого ресурса. Мы называем это "пространством имен". Если вы используете ref для ресурса с дублированным именем, он будет разрешен в ресурс в том же пространстве имен (пакет или проект) или вызовет ошибку из-за неоднозначной ссылки. Используйте двухаргументный ref для устранения неоднозначности ссылок, указав пространство имен.

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

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

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

Если вы только начинаете, ознакомьтесь с тем, как мы (dbt Labs) структурируем наши dbt проекты.

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

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

• Напишите некорректный SQL, чтобы вызвать ошибку — сможете ли вы отладить ошибку?
• Запустите только одну модель за раз. Для получения дополнительной информации смотрите Обзор синтаксиса.
• Сгруппируйте ваши модели с префиксом stg_ в подкаталог staging. Например, models/staging/stg_customers.sql.
  • Настройте ваши staging модели как представления (views).
  • Запустите только staging модели.

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

• Директорию target, чтобы увидеть весь скомпилированный SQL. Директория run показывает операторы create или replace table, которые выполняются, это операторы select, обернутые в правильный DDL.
• Файл logs, чтобы увидеть, как dbt Core регистрирует все действия, происходящие в вашем проекте. Он показывает операторы select, которые выполняются, и python логирование, происходящее при выполнении dbt.

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

Добавление тестов в проект помогает убедиться, что ваши модели работают правильно.

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

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

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

   models/schema.yml

   version: 2
   
   models:
     - name: customers
       columns:
         - name: customer_id
           tests:
             - unique
             - not_null
   
     - name: stg_customers
       columns:
         - name: customer_id
           tests:
             - unique
             - not_null
   
     - name: stg_orders
       columns:
         - name: order_id
           tests:
             - unique
             - not_null
         - name: status
           tests:
             - accepted_values:
                 values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
         - name: customer_id
           tests:
             - not_null
             - relationships:
                 to: ref('stg_customers')
                 field: customer_id
   

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

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

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

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

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

• unique
• not_null
• accepted_values
• relationships (т.е. ссылочная целостность)

Вы также можете написать свои собственные пользовательские тесты схемы данных.

Некоторые дополнительные пользовательские тесты схемы были опубликованы с открытым исходным кодом в пакете dbt-utils, ознакомьтесь с документацией по пакетам, чтобы узнать, как сделать эти тесты доступными в вашем проекте.

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

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

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

dbt test --select customers

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

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

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

• dbt Cloud:

  • В выводе теста нажмите на неудачный тест, а затем выберите "Details"

• dbt Core:

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

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

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

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

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

Посмотрите документацию для получения дополнительной информации.

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

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

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

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

Какие тесты следует добавить в мой проект?

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

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

В продвинутых проектах dbt мы рекомендуем использовать sources и запускать эти тесты целостности данных источника против источников, а не моделей.

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

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

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

Добавление документации в ваш проект позволяет подробно описывать ваши модели и делиться этой информацией с вашей командой. Здесь мы добавим базовую документацию в наш проект.

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

   models/schema.yml

   version: 2
   
   models:
     - name: customers
       description: Одна запись на каждого клиента
       columns:
         - name: customer_id
           description: Первичный ключ
           tests:
             - unique
             - not_null
         - name: first_order_date
           description: NULL, если клиент еще не сделал заказ.
   
     - name: stg_customers
       description: Эта модель очищает данные о клиентах
       columns:
         - name: customer_id
           description: Первичный ключ
           tests:
             - unique
             - not_null
   
     - name: stg_orders
       description: Эта модель очищает данные о заказах
       columns:
         - name: order_id
           description: Первичный ключ
           tests:
             - unique
             - not_null
         - name: status
           tests:
             - accepted_values:
                 values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
         - name: customer_id
           tests:
             - not_null
             - relationships:
                 to: ref('stg_customers')
                 field: customer_id

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

3. Выполните команду dbt docs serve, чтобы запустить документацию на локальном веб-сайте.

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

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

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

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

  version: 2

  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. Этот метод рекомендуется для более сложных описаний:

  version: 2

  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, чтобы написать описание в отдельном Markdown файле.

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

Если вы используете dbt Cloud для развертывания вашего проекта и у вас есть план Team или Enterprise, вы можете использовать dbt Explorer для просмотра ресурсов вашего проекта (таких как модели, тесты и метрики) и их происхождения данных, чтобы лучше понять его текущее состояние в производстве.

Получите доступ к dbt Explorer в dbt Cloud, нажав на ссылку Explore в навигации. Вы можете предоставить доступ к документации вашего проекта до 5 пользователям с правами только для чтения.

Пользователи плана разработчика dbt Cloud и dbt Core могут использовать dbt Docs, который генерирует базовую документацию, но не предлагает такую же скорость, метаданные или видимость, как dbt Explorer.

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

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

• Напишите тест, который не пройдет, например, исключите один из статусов заказа из списка accepted_values. Как выглядит неудачный тест? Можете ли вы отладить ошибку?
• Запустите тесты только для одной модели. Если вы сгруппировали свои модели с префиксом stg_ в отдельную директорию, попробуйте запустить тесты для всех моделей в этой директории.
• Используйте блок документации, чтобы добавить описание в формате Markdown к модели.

Зафиксируйте обновленные изменения

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

1. Добавьте все ваши изменения в git: git add -A
2. Зафиксируйте ваши изменения: git commit -m "Add customers model, tests, docs"
3. Отправьте ваши изменения в ваш репозиторий: git push
4. Перейдите в ваш репозиторий и откройте pull request, чтобы объединить код в вашу основную ветку.

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

Мы рекомендуем использовать dbt Cloud как самый простой и надежный способ развертывания заданий и автоматизации вашего dbt проекта в производственной среде.

Для получения дополнительной информации о том, как начать, обратитесь к созданию и планированию заданий.

Обзор выполнения задания в dbt Cloud, который включает детали выполнения задания, тип триггера, commit SHA, имя окружения, детализированные шаги выполнения, логи и многое другое.

Для получения дополнительной информации о том, как использовать dbt Core для планирования задания, обратитесь к блогу dbt airflow.