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

dbt Cloud

Quickstart

Snowflake

Beginner

Menu

Введение

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

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

Snowflake также предоставляет руководство по быстрому старту, чтобы вы могли научиться использовать dbt Cloud. Оно использует другой публичный набор данных (Knoema Economy Data Atlas), чем тот, что показан в этом руководстве. Для получения дополнительной информации обратитесь к Ускорение работы команд данных с dbt Cloud и Snowflake в документации Snowflake.

Видео для вас

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

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

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

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

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

• Узнайте больше с курсами dbt Learn
• Как мы настраиваем Snowflake
• CI задания
• Развертывание заданий
• Уведомления о заданиях
• Свежесть источников

Создание нового рабочего листа Snowflake

1. Войдите в свой пробный аккаунт Snowflake.
2. В интерфейсе Snowflake нажмите + Worksheet в правом верхнем углу, чтобы создать новый рабочий лист.

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

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

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

   Для этого выполните эти SQL-команды, введя их в редакторе вашего нового рабочего листа 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 создайте три таблицы и загрузите в них соответствующие данные:

   • Сначала удалите все содержимое (очистите) в редакторе рабочего листа Snowflake. Затем выполните эту SQL-команду, чтобы создать таблицу customer:

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

   • Удалите все содержимое в редакторе, затем выполните эту команду, чтобы загрузить данные в таблицу 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
         ); 

   • Удалите все содержимое в редакторе (очистите), затем выполните эту команду, чтобы создать таблицу orders:

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

   • Удалите все содержимое в редакторе, затем выполните эту команду, чтобы загрузить данные в таблицу 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
         );

   • Удалите все содержимое в редакторе (очистите), затем выполните эту команду, чтобы создать таблицу payment:

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

   • Удалите все содержимое в редакторе, затем выполните эту команду, чтобы загрузить данные в таблицу 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 Cloud к Snowflake

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

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

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

1. В интерфейсе Snowflake нажмите на значок дома в левом верхнем углу. В левой боковой панели выберите Data Products. Затем выберите Partner Connect. Найдите плитку dbt, прокручивая или используя поиск по 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 Cloud, вас попросят указать имя аккаунта. Если вы не создали аккаунт, вас попросят указать имя аккаунта и пароль.

dbt Cloud - Account Info

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

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

dbt Cloud - Snowflake Project Overview

dbt Cloud - Update Database and Warehouse

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

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

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

3. Для склада нажмите Snowflake, затем Next, чтобы настроить ваше подключение.

   dbt Cloud - Choose Snowflake Connection

4. Введите ваши Settings для Snowflake с:

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

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

   • Role — Оставьте пустым на данный момент. Вы можете обновить это до роли по умолчанию в Snowflake позже.

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

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

   dbt Cloud - Snowflake Account Settings

5. Введите ваши Development Credentials для Snowflake с:

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

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

7. Если тест подключения прошел успешно, нажмите Next. Если он не удался, возможно, вам нужно проверить настройки и учетные данные Snowflake.

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

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

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

Чтобы подключиться к репозиторию, вы можете либо настроить размещаемый в dbt Cloud управляемый репозиторий, либо напрямую подключиться к поддерживаемому git-провайдеру. Управляемые репозитории — отличный способ попробовать dbt без необходимости создавать новый репозиторий. В долгосрочной перспективе лучше подключиться к поддерживаемому git-провайдеру, чтобы использовать такие функции, как автоматизация и непрерывная интеграция.

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

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

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

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

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

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

к сведению

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

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

Примечание: Замените snowflake_role_name на роль, которую вы собираетесь использовать. Если вы запустили dbt Cloud с помощью 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;

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

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

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

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

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

Одной из самых мощных функций 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 в нашем исходном запросе.

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

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

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

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

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

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

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

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

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

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

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

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. Нажмите на значок книги в интерфейсе 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 Explorer?

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

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

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

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

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

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

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

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

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 введите название набора данных, который вы хотите использовать в качестве целевого, например, "Analytics". Это позволит dbt строить и работать с этим набором данных. Для некоторых хранилищ данных целевой набор данных может называться "схемой".
6. Нажмите Save.

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

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

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

1. После создания вашей среды развертывания вы должны быть перенаправлены на страницу новой среды. Если нет, выберите Deploy в верхнем левом углу, затем нажмите Jobs.
2. Нажмите Create one и укажите имя, например, "Production run", и свяжите с только что созданной средой.
3. Прокрутите вниз до раздела Execution Settings.
4. В разделе Commands добавьте эту команду как часть вашего задания, если вы ее не видите:
   • dbt build
5. Выберите флажок Generate docs on run, чтобы автоматически генерировать обновленную документацию проекта каждый раз, когда выполняется ваше задание.
6. Для этого упражнения не устанавливайте расписание для выполнения вашего проекта — хотя проект вашей организации должен выполняться регулярно, нет необходимости запускать этот пример проекта по расписанию. Планирование задания иногда называют развертыванием проекта.
7. Выберите Save, затем нажмите Run now, чтобы запустить ваше задание.
8. Нажмите на выполнение и наблюдайте за его прогрессом в разделе "Run history."
9. После завершения выполнения нажмите View Documentation, чтобы увидеть документацию вашего проекта.

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

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

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

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