Перейти к основному содержимому

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

Быстрый старт
Начальный уровень
Menu

    Введение​

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

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

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

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

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

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

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

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

    1. Создайте новый репозиторий GitHub с именем dbt-tutorial.

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

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

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

    5. Сохраните команды из раздела «…or create a new repository on the command line», чтобы использовать их позже в шаге Commit your changes.

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

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

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

    1. Убедитесь, что у вас установлен dbt, и проверьте версию с помощью команды dbt --version:
    dbt --version
    1. Инициализируйте проект jaffle_shop с помощью команды init:
    dbt init jaffle_shop
    1. Перейдите в директорию вашего проекта:
    cd jaffle_shop
    1. Используйте pwd, чтобы убедиться, что вы находитесь в нужном месте:
    $ pwd
    > Users/BBaggins/dbt-tutorial/jaffle_shop
    1. Откройте каталог проекта, созданный на предыдущих шагах и названный jaffle_shop, в редакторе кода, например VS Code. В нём находятся папки, а также файлы .sql и .yml, созданные командой init.
    Стартовый проект в текстовом редактореСтартовый проект в текстовом редакторе
    1. 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 подключается к вашему data warehouse с помощью профиля — 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/KEYFILE_NAME.json # Замените на полный путь к вашему файлу ключа
    database: GCP_PROJECT_ID # Идентификатор вашего проекта Google Cloud
    schema: dbt_YOUR_NAME # Ваш набор данных для разработки, например dbt_bbaggins
    threads: 4
    location: US # Должно совпадать с расположением ваших наборов данных BigQuery
    1. Запустите команду debug из вашего проекта, чтобы подтвердить, что вы можете успешно подключиться:
    $ dbt debug
    > Connection test: OK connection ok
    Успешная команда dbt debugУспешная команда dbt debug

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

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

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

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

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

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

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

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

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

    1. Свяжите созданный вами репозиторий GitHub с вашим проектом dbt, выполнив следующие команды в Terminal. Убедитесь, что вы используете корректный git URL вашего репозитория, который вы должны были сохранить на шаге 5 в разделе Create a repository.
    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
    1. Вернитесь в ваш репозиторий GitHub, чтобы убедиться, что ваши новые файлы были добавлены.

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

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

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

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

    1. Создайте новую ветку, используя команду checkout и передав флаг -b:
    $ git checkout -b add-customers-model
    > Switched to a new branch `add-customer-model`

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

    Если вы хотите использовать ИИ для создания своей первой модели, ознакомьтесь с разделом Создание модели с помощью dbt Wizard ниже.

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

    select
    id as customer_id,
    first_name,
    last_name

    from `dbt-tutorial`.jaffle_shop.customers

    ),

    orders as (

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

    from `dbt-tutorial`.jaffle_shop.orders

    ),

    customer_orders as (

    select
    customer_id,

    min(order_date) as first_order_date,
    max(order_date) as most_recent_order_date,
    count(order_id) as number_of_orders

    from orders

    group by 1

    ),

    final as (

    select
    customers.customer_id,
    customers.first_name,
    customers.last_name,
    customer_orders.first_order_date,
    customer_orders.most_recent_order_date,
    coalesce(customer_orders.number_of_orders, 0) as number_of_orders

    from customers

    left join customer_orders using (customer_id)

    )

    select * from final

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

    1. Из командной строки введите dbt run.
    Успешное выполнение dbt из командной строкиУспешное выполнение dbt из командной строки

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

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

    Как посмотреть SQL, который выполняет dbt?
    Как dbt выбирает, в какой схеме строить мои модели?
    Нужно ли создавать целевую схему перед запуском dbt?
    Если я перезапущу dbt, будет ли простой, пока модели перестраиваются?
    Что произойдет, если в моем SQL-запросе ошибка или я получу ошибку базы данных?

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

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

    1. Установите CLI dbt Wizard:
    curl -fsSL https://public.cdn.getdbt.com/dbt-wizard/install/install-wizard.sh | sh
    1. Запустите wizard в каталоге проекта, чтобы начать сеанс, а затем пройдите первоначальную настройку (если вы ещё этого не сделали).
    Сеанс dbt Wizard в терминалеСеанс dbt Wizard в терминале
    1. Введите запрос: «Создай модель customers, которая объединяет orders и customers и включает дату последнего заказа и общее количество заказов для каждого клиента».
    2. Проверьте SQL, сгенерированный dbt Wizard, а затем примите его, чтобы сохранить модель.
    3. Введите dbt run, чтобы построить её.

    В любом случае вы получите одну и ту же работающую модель. Подробные инструкции по настройке см. в разделе Локальное использование dbt Wizard.

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

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

    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. Сохраните изменения.

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

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

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

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

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

    Граф, который мы хотим для нашего проекта dbtГраф, который мы хотим для нашего проекта 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 `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
    1. Отредактируйте 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

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

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

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

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

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

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

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

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

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

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

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

    Чтобы добавить 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? Могу ли я добавить свои собственные тесты?
    Как протестировать одну модель за раз?
    Один из моих тестов не прошел, как я могу его отладить?
    Должен ли мой файл с тестами называться `schema.yml`?
    Почему файлы YAML для моделей и источников всегда начинаются с `version: 2`?
    Какие тесты данных стоит добавить в проект?
    Когда следует запускать data tests?

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

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

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

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

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

    Обновите файл 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: # доступно в версии v1.10.5 и выше. В более ранних версиях <argument_name> можно задать как свойство верхнего уровня.
    values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
    - name: customer_id
    data_tests:
    - not_null
    - relationships:
    arguments:
    to: ref('stg_customers')
    field: customer_id
    1. Выполните dbt docs generate, чтобы скомпилировать артефакты, необходимые для статического сайта документации вашего проекта.
    2. Выполните dbt docs serve, чтобы открыть документацию на локальном веб-сайте.

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

    Как писать развернутые объяснения в описаниях?
    Как получить доступ к документации в dbt Catalog?

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

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

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

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

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

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

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

    Чтобы самостоятельно настроить расписание заданий с помощью оркестратора, например Airflow, обратитесь к статье в блоге dbt и Airflow.

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

    Теперь, когда ваш проект настроен и работает, подключите к нему свой ИИ-инструмент (например, Claude или ChatGPT) через dbt MCP server, чтобы задавать вопросы о моделях на естественном языке. Описания, тесты и семантические модели помогут сделать его ответы ещё лучше.

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

    0