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

Назад к гайдам

dbt platform

Quickstart

Snowflake

Beginner

Menu

Введение

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

• Создать новый worksheet в Snowflake.
• Загрузить пример данных в ваш аккаунт Snowflake.
• Подключить dbt к Snowflake.
• Взять пример запроса и превратить его в модель в вашем dbt‑проекте. Модель в dbt — это SQL‑запрос select.
• Добавить источники (sources) в ваш dbt‑проект. Источники позволяют именовать и описывать сырые данные, уже загруженные в Snowflake.
• Добавить тесты к вашим моделям.
• Задокументировать ваши модели.
• Запланировать выполнение job.

Snowflake также предоставляет собственный quickstart, который поможет вам изучить использование dbt. В нем используется другой публичный датасет (Knoema Economy Data Atlas), отличный от того, что показан в этом руководстве. Подробнее см. Accelerating Data Teams with dbt & Snowflake в документации Snowflake.

Видео для вас

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

Также вы можете посмотреть видео на YouTube про dbt и Snowflake.

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

• У вас есть аккаунт dbt.
• У вас есть trial‑аккаунт Snowflake. При создании trial‑аккаунта обязательно выберите редакцию Snowflake Enterprise, чтобы у вас был доступ ACCOUNTADMIN. Для полноценного внедрения стоит учитывать организационные вопросы при выборе облачного провайдера. Подробнее см. Introduction to Cloud Platforms в документации Snowflake. Для целей этой настройки подойдут любые облачные провайдеры и регионы — выбирайте любой удобный.

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

• Узнайте больше с помощью курсов dbt Learn
• Как мы настраиваем Snowflake
• CI jobs
• Deploy jobs
• Уведомления о job
• Актуальность источников (Source freshness)

Создание нового Snowflake worksheet

1. Войдите в ваш trial‑аккаунт Snowflake.
2. В интерфейсе Snowflake нажмите + Create в левом верхнем углу под логотипом Snowflake — откроется выпадающее меню. Выберите первый пункт SQL Worksheet.

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

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

1. Создайте новый виртуальный warehouse, две новые базы данных (одну для сырых данных, вторую — для будущей разработки в dbt) и две новые схемы (одну для данных jaffle_shop, другую — для данных stripe).

   Для этого выполните следующие SQL‑команды: введите их в Editor нового worksheet в Snowflake и нажмите Run в правом верхнем углу интерфейса:

   create warehouse transforming;
   create database raw;
   create database analytics;
   create schema raw.jaffle_shop;
   create schema raw.stripe;

2. В базе данных raw и схемах jaffle_shop и stripe создайте три таблицы и загрузите в них соответствующие данные:

   • Сначала удалите всё содержимое (очистите Editor) в worksheet Snowflake. Затем выполните следующую SQL‑команду для создания таблицы customer:

     create table raw.jaffle_shop.customers 
     ( id integer,
       first_name varchar,
       last_name varchar
     );

   • Очистите Editor, затем выполните эту команду для загрузки данных в таблицу customer:

     copy into raw.jaffle_shop.customers (id, first_name, last_name)
     from 's3://dbt-tutorial-public/jaffle_shop_customers.csv'
     file_format = (
         type = 'CSV'
         field_delimiter = ','
         skip_header = 1
         ); 

   • Очистите Editor (оставьте его пустым), затем выполните эту команду для создания таблицы orders:

     create table raw.jaffle_shop.orders
     ( id integer,
       user_id integer,
       order_date date,
       status varchar,
       _etl_loaded_at timestamp default current_timestamp
     );

   • Очистите Editor, затем выполните эту команду для загрузки данных в таблицу orders:

     copy into raw.jaffle_shop.orders (id, user_id, order_date, status)
     from 's3://dbt-tutorial-public/jaffle_shop_orders.csv'
     file_format = (
         type = 'CSV'
         field_delimiter = ','
         skip_header = 1
         );

   • Очистите Editor (оставьте его пустым), затем выполните эту команду для создания таблицы payment:

     create table raw.stripe.payment 
     ( id integer,
       orderid integer,
       paymentmethod varchar,
       status varchar,
       amount integer,
       created date,
       _batched_at timestamp default current_timestamp
     );

   • Очистите Editor, затем выполните эту команду для загрузки данных в таблицу payment:

     copy into raw.stripe.payment (id, orderid, paymentmethod, status, amount, created)
     from 's3://dbt-tutorial-public/stripe_payments.csv'
     file_format = (
         type = 'CSV'
         field_delimiter = ','
         skip_header = 1
         );

3. Убедитесь, что данные успешно загружены, выполнив следующие SQL‑запросы. Подтвердите, что для каждого из них отображается результат:

   select * from raw.jaffle_shop.customers;
   select * from raw.jaffle_shop.orders;
   select * from raw.stripe.payment;   

Подключение dbt к Snowflake

Существует два способа подключить dbt к Snowflake. Первый — Partner Connect, который предоставляет упрощенную настройку и позволяет создать аккаунт dbt прямо из вашего нового trial‑аккаунта Snowflake. Второй — создать аккаунт dbt отдельно и настроить подключение к Snowflake вручную. Если вы хотите начать как можно быстрее, dbt Labs рекомендует использовать Partner Connect. Если же вы хотите с самого начала кастомизировать настройку и лучше разобраться в процессе конфигурации dbt, dbt Labs рекомендует ручное подключение.

Использовать Partner Connect

Использование Partner Connect позволяет создать полноценный dbt‑аккаунт с подключением к Snowflake, управляемым репозиторием, окружениями и учетными данными.

1. В интерфейсе Snowflake нажмите на иконку «домой» в левом верхнем углу. В левой боковой панели выберите Data Products, затем — Partner Connect. Найдите плитку dbt, прокрутив список или воспользовавшись поиском. Нажмите на плитку, чтобы подключиться к dbt.

   Snowflake Partner Connect Box

   Если вы используете классическую версию интерфейса Snowflake, нажмите кнопку Partner Connect в верхней панели аккаунта. Затем нажмите на плитку dbt, чтобы открыть окно подключения.

   Snowflake Classic UI - Partner Connect

2. Во всплывающем окне Connect to dbt найдите опцию Optional Grant и выберите базы данных RAW и ANALYTICS. Это предоставит доступ новой роли пользователя dbt к каждой базе данных. Затем нажмите Connect.

   Snowflake Classic UI - Connection Box
   Snowflake New UI - Connection Box

3. Когда появится всплывающее окно, нажмите Activate:

Snowflake Classic UI - Actviation Window

Snowflake New UI - Activation Window

4. После загрузки новой вкладки вы увидите форму. Если вы уже создавали аккаунт dbt, вас попросят указать имя аккаунта. Если аккаунт еще не создан — потребуется указать имя аккаунта и пароль.

5. После заполнения формы и нажатия Complete Registration вы будете автоматически авторизованы в dbt.

6. В левом меню нажмите на имя аккаунта, затем выберите Account settings, выберите проект "Partner Connect Trial" и в таблице overview выберите snowflake. Нажмите edit и обновите поля Database и Warehouse, установив значения analytics и transforming соответственно.

dbt - Snowflake Project Overview

dbt - Update Database and Warehouse

Подключить вручную

1. Создайте новый проект в dbt. Перейдите в Account settings (нажав на имя аккаунта в левом меню) и нажмите + New Project.

2. Введите имя проекта и нажмите Continue.

3. В разделе Configure your development environment откройте выпадающее меню Connection и выберите Add new connection. Это перенаправит вас к настройкам подключения.

4. В разделе Type выберите Snowflake.

   dbt - Choose Snowflake Connection

5. Укажите Settings для Snowflake:

   • Account — Найдите ваш аккаунт, используя URL trial‑аккаунта Snowflake, удалив из него snowflakecomputing.com. Порядок информации в аккаунте зависит от версии Snowflake. Например, URL классической консоли может выглядеть так: oq65696.west-us-2.azure.snowflakecomputing.com. URL AppUI или Snowsight может выглядеть так: snowflakecomputing.com/west-us-2.azure/oq65696. В обоих случаях значением аккаунта будет: oq65696.west-us-2.azure. Подробнее см. Account Identifiers в документации Snowflake.

       ✅ db5261993 или db5261993.east-us-2.azure
       ❌ db5261993.eu-central-1.snowflakecomputing.com

   • Role — Пока оставьте пустым. Позже вы сможете задать роль Snowflake по умолчанию.

   • Database — analytics. Это указывает dbt создавать новые модели в базе данных analytics.

   • Warehouse — transforming. Это указывает dbt использовать warehouse transforming, созданный ранее.

   dbt - Snowflake Account Settings

6. Нажмите Save.

7. Настройте персональные учетные данные для разработки, перейдя в Your profile > Credentials.

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

9. Нажмите ссылку configure your development environment and add a connection. Вы перейдете на страницу ввода персональных учетных данных.

10. Введите Development credentials для Snowflake:

    • Username — Имя пользователя, созданное в Snowflake. Обычно это не email, а имя и фамилия, объединенные в одно слово.
    • Password — Пароль, заданный при создании аккаунта Snowflake.
    • Schema — Обратите внимание, что имя схемы было создано автоматически. По соглашению это dbt_<first-initial><last-name>. Эта схема напрямую связана с вашим окружением разработки, и именно здесь будут создаваться модели при запуске dbt в Studio IDE.
    • Target name — Оставьте значение по умолчанию.
    • Threads — Оставьте значение 4. Это количество одновременных подключений, которые dbt будет использовать для параллельной сборки моделей.
    dbt - Snowflake Development Credentials

11. Нажмите Test connection. Это проверит, что dbt может получить доступ к вашему аккаунту Snowflake.

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

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

Если вы использовали Partner Connect, можете перейти сразу к разделу инициализация dbt‑проекта, так как Partner Connect уже предоставляет управляемый репозиторий. В противном случае вам потребуется создать подключение к репозиторию вручную.

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

Чтобы подключиться к репозиторию, вы можете либо настроить размещённый в dbt managed repository, либо напрямую подключиться к поддерживаемому git‑провайдеру. Managed repositories — это отличный способ попробовать dbt без необходимости создавать новый репозиторий. В долгосрочной перспективе лучше подключиться к поддерживаемому git‑провайдеру, чтобы использовать такие возможности, как автоматизация и непрерывная интеграция.

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

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

Инициализация dbt‑проекта и начало разработки

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

1. Нажмите Start developing in the Studio IDE. При первом запуске это может занять несколько минут, так как настраивается git‑подключение, клонируется репозиторий и проверяется соединение с warehouse.
2. Над деревом файлов слева нажмите Initialize your project. Это создаст структуру папок с примерами моделей.
3. Сделайте первый коммит, нажав Commit and sync. Используйте сообщение коммита initial commit. Это создаст первый коммит в управляемом репозитории и позволит открыть новую ветку для добавления dbt‑кода.
4. Теперь вы можете напрямую выполнять запросы к warehouse и запускать dbt run. Попробуйте сделать это сейчас:
   • Нажмите + Create new file, добавьте следующий запрос в новый файл и нажмите Save as:

     select * from raw.jaffle_shop.customers
   • В командной строке внизу введите dbt run и нажмите Enter. Вы должны увидеть сообщение dbt run succeeded.

к сведению

Если на этом этапе вы получаете ошибку недостаточных прав доступа (insufficient privileges) в Snowflake, возможно, роль Snowflake не имеет разрешений на доступ к сырым данным, на создание целевых таблиц и представлений, или и на то и на другое.

Для устранения проблемы используйте роль с достаточными правами (например, ACCOUNTADMIN) и выполните следующие команды в Snowflake.

Примечание: Замените snowflake_role_name на роль, которую вы планируете использовать. Если вы запускали dbt через Snowflake Partner Connect, используйте роль pc_dbt_role.

grant all on database raw to role snowflake_role_name;
grant all on database analytics to role snowflake_role_name;

grant all on schema raw.jaffle_shop to role snowflake_role_name;
grant all on schema raw.stripe to role snowflake_role_name;

grant all on all tables in database raw to role snowflake_role_name;
grant all on future tables in database raw to role snowflake_role_name;

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

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

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

Назовите новую ветку add-customers-model.

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

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

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

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

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

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

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

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

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

     dbt_project.yml

     name: 'jaffle_shop'

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

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

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

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

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

• теги для поддержки легкой категоризации и выбора графа
• пользовательские схемы для разделения ваших моделей по нескольким схемам
• алиасы, если имя вашего view/table должно отличаться от имени файла
• Фрагменты 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, могут остаться лишние объекты, что может запутать других пользователей.

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

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

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

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

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

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

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

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

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

1. Создайте новый SQL‑файл models/stg_customers.sql с SQL из CTE customers в нашем исходном запросе.

2. Создайте второй SQL‑файл models/stg_orders.sql с SQL из CTE orders в нашем исходном запросе.

   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 проекты.

Построение моделей поверх источников

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

• выбирать данные из source‑таблиц в моделях с помощью функции {{ source() }}, определяя lineage данных;
• проверять ваши предположения о качестве исходных данных;
• рассчитывать актуальность (freshness) исходных данных.

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

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

   models/sources.yml

   
   sources:
       - name: jaffle_shop
         description: This is a replica of the Postgres database used by our app
         database: raw
         schema: jaffle_shop
         tables:
             - name: customers
               description: One record per customer.
             - name: orders
               description: One record per order. Includes cancelled and deleted orders.

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

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

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

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

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

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

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

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

   models/schema.yml

   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 (т.е. ссылочная целостность)

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

Некоторые дополнительные пользовательские schema tests были выложены в open source в пакете dbt-utils. Ознакомьтесь с документацией по packages, чтобы узнать, как сделать эти тесты доступными в вашем проекте.

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

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

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

dbt test --select customers

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

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

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

• dbt:

  • В выводе результатов теста нажмите на упавший тест, а затем выберите "Details".

• dbt Core:

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

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

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

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

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

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

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

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

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

Начиная с dbt Core v1.5, ключ верхнего уровня version: является необязательным во всех ресурсных YAML‑файлах. Если он указан, поддерживается только version: 2.

Также, начиная с версии 1.5, и config-version: 2, и ключ верхнего уровня version: в файле dbt_project.yml являются необязательными.

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

What data tests should I add to my project?

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

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

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

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

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

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

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

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

   models/schema.yml

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

  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 Catalog?

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

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

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

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

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

Если вы редактировали прямо в защищённой основной ветке:

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, чтобы добавить эти изменения в ветку main вашего репозитория.

Если вы создали новую ветку до редактирования:

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

Разверните dbt

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

Создайте окружение развертывания (deployment environment)

1. В главном меню перейдите в Orchestration > Environments.
2. Нажмите Create environment.
3. В поле Name введите имя окружения развертывания. Например, «Production».
4. В поле dbt Version выберите последнюю версию из выпадающего списка.
5. В разделе Deployment connection укажите имя датасета, который вы хотите использовать как target, например «Analytics». Это позволит dbt собирать объекты и работать с этим датасетом. В некоторых хранилищах данных целевой датасет может называться «schema».
6. Нажмите Save.

Создайте и запустите job

Jobs — это набор команд dbt, которые вы хотите запускать по расписанию. Например, dbt build.

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

1. После создания окружения развертывания вы должны попасть на страницу нового окружения. Если нет — в главном меню выберите Orchestration, затем нажмите Jobs.
2. Нажмите Create job > Deploy job.
3. Укажите имя job (например, «Production run») и выберите окружение, которое вы только что создали.
4. Прокрутите вниз до раздела Execution settings.
5. В разделе Commands добавьте эту команду как часть job, если её нет:
   • dbt build
6. Выберите опцию Generate docs on run, чтобы автоматически генерировать обновлённую документацию проекта при каждом запуске job.
7. Для этого упражнения не задавайте расписание запуска проекта — хотя проекты в вашей организации должны выполняться регулярно, нет необходимости запускать этот примерный проект по расписанию. Планирование job иногда называют развёртыванием проекта.
8. Нажмите Save, затем Run now, чтобы запустить job.
9. Откройте запуск и следите за прогрессом в Run summary.
10. Когда запуск завершится, нажмите View Documentation, чтобы посмотреть документацию проекта.

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

FAQs

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

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

Нашли ошибку?

Создать GitHub Issue