Краткое руководство по dbt Charts

dbt Charts

Быстрый старт

Начальный уровень

Введение

dbt Charts — это слой визуализации, который превращает YAML-файлы в интерактивные дашборды. Вы определяете запросы, диаграммы и макеты в текстовом виде и храните их в Git вместе с проектом dbt. Поскольку dbt Charts выполняет запросы непосредственно к вашим моделям dbt, дашборды остаются согласованными с теми же преобразованиями, которым ваша команда уже доверяет.

Вы разрабатываете панели dbt Charts локально с помощью инструмента командной строки dct: он читает файл панели, выполняет её запросы через подключение из вашего dbt-файла profiles.yml и отображает результат в браузере с автоматическим обновлением при редактировании.

В этом кратком руководстве вы научитесь:

Создавать каталог charts/ и файл панели вручную.
Создавать первые пять визуализаций — линейную, столбчатую, с областями, круговую диаграммы и таблицу — на основе моделей dbt.
Устанавливать dbt Charts и просматривать панель локально.

В этом руководстве используется пример проекта fusion-jaffle-shop, рассчитанный на v1.12+ и включающий такие витрины данных, как order_items и location_performance. По завершении у вас будет панель, которая показывает динамику выручки, сравнивает показатели разных магазинов и отображает ключевые показатели эффективности (KPI) для каждого магазина.

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

У вас установлен dbt v1.12+. В этом руководстве предполагается использование dbt v2.
- Если вы используете v2, необходимо установить адаптер v1, чтобы проект dbt Charts загружался в браузере. Дополнительная настройка не требуется. Например, если вы используете Snowflake, выполните pip install dbt-snowflake перед установкой dbt Charts. По мере развития dbt Charts это требование будет снято.
У вас установлен Git, и вы знакомы с основами работы в командной строке и с YAML.
У вас установлен Python 3.9 или более поздней версии и менеджер пакетов, например uv или pip, для установки инструмента dct.
У вас есть рабочее подключение к платформе данных (в этом руководстве используется Snowflake), на которой dbt может создавать модели.

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

Клонирование примера проекта и его сборка

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

Клонируйте пример проекта и перейдите в его каталог:
```
git clone https://github.com/matthewshaver/jaffle-shop-multi-adapter.git
cd fusion-jaffle-shop
```
Добавьте profiles.yml для вашей платформы данных. В файле dbt_project.yml проекта задано profile: default, поэтому назовите профиль default и добавьте в него целевое окружение dev. dbt читает profiles.yml из корня проекта, а если его там нет — использует ~/.dbt/profiles.yml. Поля для конкретной платформы описаны в разделе Профили подключения.
Установите пакеты проекта:
```
dbt deps
```
Загрузите исходные CSV-файлы как seed-данные, создайте модели и запустите тесты одной командой:
```
dbt build
```
Команда dbt build выполняет seed-файлы, модели, снимки и тесты в порядке зависимостей, поэтому отдельный шаг dbt seed не нужен. Полный список команд приведён в разделе Команды dbt.
Убедитесь, что витрина данных, к которой будут обращаться диаграммы, возвращает строки:
```
dbt show --inline "select count(*) from {{ ref('order_items') }}"
```

примечание

Запишите базу данных и схему, в которых dbt создал модели, — они понадобятся в SQL-запросах диаграмм. Чтобы найти их, выполните dbt list --output json и посмотрите значение relation_name для каждой модели.

Создание каталога charts и файла панели

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

В корне проекта создайте каталог для панелей:
```
mkdir charts
```
Каждый файл .yaml, .yml и .md в каталоге charts/ становится доступной для просмотра страницей, а вложенные каталоги — вложенными путями.
Создайте dbt_charts.yml в корне проекта. При локальной работе dbt Charts использует ваше подключение dbt — отдельная настройка учётных данных не требуется. Объявите источник, указывающий на профиль и целевое окружение dbt, а в панелях ссылайтесь на него по имени:
dbt_charts.yml
```
sources:
  analytics:
    type: dbt_profile
    profile: default
    target: dev
```
Значения profile и target должны соответствовать вашему profiles.yml (default и dev в этом проекте). Учётные данные остаются в profiles.yml, включая аутентификацию Snowflake по паре ключей через private_key_path, если она требуется для вашей учётной записи.
Создайте пустой файл панели charts/analytics.yml и укажите в нём заголовок и источник:
charts/analytics.yml
```
title: "Jaffle Shop overview"
source: analytics
```

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

Добавление первых пяти диаграмм

Теперь добавьте в charts/analytics.yml пять визуализаций — по одной для каждого из наиболее распространённых типов. Каждая диаграмма ссылается на SQL-запрос, определённый в блоке queries:, и сопоставляет выходные столбцы этого запроса с каналами диаграммы (x, y, theta, color).

Каждый фрагмент ниже содержит запрос и диаграмму, которые нужно добавить. Диаграммы не отобразятся, пока вы не добавите макет на следующем шаге; полный файл приведён в разделе Размещение элементов панели.

Каждый запрос ссылается на модель по её полному имени. Замените MY_DATABASE.MY_SCHEMA на базу данных и схему, в которых dbt создал ваши витрины данных. В SQL используется синтаксис Snowflake, поэтому при работе с другой платформой адаптируйте такие функции, как date_trunc.

1. Линейная диаграмма: динамика выручки

Линейные диаграммы показывают изменение показателей во времени. Этот запрос агрегирует выручку по месяцам на основе модели order_items.

queries:
  revenue_by_month:
    sql: |
      SELECT date_trunc('month', ordered_at) AS month,
             sum(product_price) AS revenue
      FROM MY_DATABASE.MY_SCHEMA.order_items
      GROUP BY 1
      ORDER BY 1

charts:
  revenue_trend:
    type: line
    query: revenue_by_month
    x: month
    y: revenue
    title: "Revenue by month"
Сообщить об ошибке в коде

2. Столбчатая диаграмма: выручка по магазинам

Столбчатые диаграммы позволяют сравнивать значения между категориями. Этот запрос получает предварительно агрегированную выручку по каждому магазину из витрины location_performance.

queries:
  revenue_by_location:
    sql: |
      SELECT location_name,
             total_revenue AS revenue
      FROM MY_DATABASE.MY_SCHEMA.location_performance
      ORDER BY total_revenue DESC

charts:
  revenue_by_location:
    type: bar
    query: revenue_by_location
    x: location_name
    y: revenue
    title: "Revenue by location"
Сообщить об ошибке в коде

3. Диаграмма с областями: накопленная выручка

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

queries:
  cumulative_revenue:
    sql: |
      SELECT month,
             sum(revenue) OVER (ORDER BY month) AS cumulative_revenue
      FROM (
        SELECT date_trunc('month', ordered_at) AS month,
               sum(product_price) AS revenue
        FROM MY_DATABASE.MY_SCHEMA.order_items
        GROUP BY 1
      )
      ORDER BY month

charts:
  cumulative_revenue:
    type: area
    query: cumulative_revenue
    x: month
    y: cumulative_revenue
    title: "Cumulative revenue"
Сообщить об ошибке в коде

4. Круговая диаграмма: выручка по типам продуктов

Круговые (секторные) диаграммы показывают соотношение частей и целого. Этот запрос разделяет выручку на еду и напитки. Секторная диаграмма использует theta для размера сектора и color для категории.

queries:
  revenue_by_type:
    sql: |
      SELECT CASE WHEN is_food_item
                  THEN 'Food' ELSE 'Drink' END AS product_type,
             sum(product_price) AS revenue
      FROM MY_DATABASE.MY_SCHEMA.order_items
      GROUP BY 1

charts:
  revenue_by_type:
    type: pie
    query: revenue_by_type
    theta: revenue
    color: product_type
    title: "Revenue by product type"
Сообщить об ошибке в коде

5. Таблица: KPI магазинов

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

queries:
  location_kpis:
    sql: |
      SELECT location_name,
             total_revenue,
             total_orders,
             avg_order_value
      FROM MY_DATABASE.MY_SCHEMA.location_performance
      ORDER BY total_revenue DESC

charts:
  location_kpis_table:
    type: table
    query: location_kpis
    title: "Location KPIs"
Сообщить об ошибке в коде

Размещение элементов панели

Диаграммы не появятся, пока вы не укажете их в макете. В панелях используется rows: для вертикального размещения содержимого и cols: для размещения элементов рядом друг с другом. Объедините запросы и диаграммы из предыдущего шага в единые блоки queries: и charts:, затем добавьте макет, ссылающийся на каждую диаграмму по её ID.

Теперь ваш полный файл charts/analytics.yml должен выглядеть следующим образом, причём MY_DATABASE.MY_SCHEMA нужно заменить на базу данных и схему, в которых dbt создал ваши витрины данных:

charts/analytics.yml

title: "Jaffle Shop overview"
source: analytics

queries:
  revenue_by_month:
    sql: |
      SELECT date_trunc('month', ordered_at) AS month,
             sum(product_price) AS revenue
      FROM MY_DATABASE.MY_SCHEMA.order_items
      GROUP BY 1
      ORDER BY 1
  revenue_by_location:
    sql: |
      SELECT location_name,
             total_revenue AS revenue
      FROM MY_DATABASE.MY_SCHEMA.location_performance
      ORDER BY total_revenue DESC
  cumulative_revenue:
    sql: |
      SELECT month,
             sum(revenue) OVER (ORDER BY month) AS cumulative_revenue
      FROM (
        SELECT date_trunc('month', ordered_at) AS month,
               sum(product_price) AS revenue
        FROM MY_DATABASE.MY_SCHEMA.order_items
        GROUP BY 1
      )
      ORDER BY month
  revenue_by_type:
    sql: |
      SELECT CASE WHEN is_food_item
                  THEN 'Food' ELSE 'Drink' END AS product_type,
             sum(product_price) AS revenue
      FROM MY_DATABASE.MY_SCHEMA.order_items
      GROUP BY 1
  location_kpis:
    sql: |
      SELECT location_name,
             total_revenue,
             total_orders,
             avg_order_value
      FROM MY_DATABASE.MY_SCHEMA.location_performance
      ORDER BY total_revenue DESC

charts:
  revenue_trend:
    type: line
    query: revenue_by_month
    x: month
    y: revenue
    title: "Revenue by month"
  revenue_by_location:
    type: bar
    query: revenue_by_location
    x: location_name
    y: revenue
    title: "Revenue by location"
  cumulative_revenue:
    type: area
    query: cumulative_revenue
    x: month
    y: cumulative_revenue
    title: "Cumulative revenue"
  revenue_by_type:
    type: pie
    query: revenue_by_type
    theta: revenue
    color: product_type
    title: "Revenue by product type"
  location_kpis_table:
    type: table
    query: location_kpis
    title: "Location KPIs"

rows:
  - title: "Trends"
    cols:
      - revenue_trend
      - cumulative_revenue
  - title: "Locations"
    cols:
      - revenue_by_location
      - revenue_by_type
  - title: "Detail"
    rows:
      - location_kpis_table
Сообщить об ошибке в коде

Теперь корневой каталог проекта должен содержать:

fusion-jaffle-shop/
├── charts/
│   └── analytics.yml      # Your board
├── dbt_charts.yml         # dbt Charts project config
├── dbt_project.yml
├── models/
├── profiles.yml
└── seeds/
Сообщить об ошибке в коде

Установка dbt Charts и просмотр панели

dbt Charts поставляется в виде пакета Python с инструментом командной строки dct.

Установите dbt Charts с помощью uv:
```
uv tool install dbt-charts
```
Или с помощью pip:
```
pip install dbt-charts
```
В корне проекта выполните проверку панели, чтобы выявить ошибки YAML, ссылок и SQL до её отображения:
```
dct validate
```
Без аргументов команда dct validate проверяет все панели в каталоге charts/. Передайте путь — dct validate charts/analytics.yml — для проверки одной панели.
Запустите локальный сервер разработки:
```
dct serve
```
dct поднимается от текущего каталога вверх в поисках dbt_charts.yml или dbt_project.yml, определяет диалект SQL по целевому окружению вашего профиля и выбирает порт на основе каталога проекта.
Откройте URL, который выведет dct. На странице перечислены все панели из каталога charts/. Выберите analytics.yml, чтобы открыть свою.

Все пять визуализаций отображаются в трёх рядах: две диаграммы динамики рядом друг с другом, две диаграммы по магазинам под ними и таблица KPI внизу. Сервер автоматически обновляет страницу при редактировании YAML, поэтому оставьте его запущенным, пока вносите изменения.
При необходимости сформируйте статический результат, чтобы поделиться им или просмотреть скомпилированный SQL:
```
dct render charts/analytics.yml --format html
```

Устранение неполадок

Ошибка проверки dbt_charts.yml: extra inputs are not permitted — dbt_charts.yml принимает фиксированный набор ключей верхнего уровня, таких как sources и server. Удалите все остальные, включая ключ name.
Диаграмма не показывает данные — Убедитесь, что подключение из profiles.yml работает (dbt debug) и что роль, указанная в профиле, имеет право SELECT для схем, к которым обращаются ваши запросы.
Некоторые диаграммы показывают данные, а на остальных только нули — Проверьте, не обращаются ли пустые диаграммы к модели, данные которой фильтруются в целевом окружении разработки. Часто для разработки данные ограничивают недавним временным интервалом, например с помощью макроса limit_in_dev для заказов. В статическом демонстрационном наборе данных такой интервал может исключить все строки и обнулить зависимые модели, тогда как модели без фильтра по-прежнему будут содержать данные. Привяжите интервал к максимальной временной метке самих данных с помощью max(), расширьте его или выполните сборку в целевом окружении, где этот фильтр не применяется.
Таблица или представление не найдены — Убедитесь, что префикс базы данных и схемы в каждом FROM соответствует месту, где dbt фактически создаёт модель. Выполните dbt list --output json и посмотрите значение relation_name, чтобы узнать точное расположение.
Столбец не найден — Каналы диаграммы (x, y, theta, color) должны соответствовать именам столбцов, которые возвращает SELECT вашего запроса. Задайте псевдонимы столбцов в SQL, чтобы имена совпадали.
Диаграмма отображается пустой — Убедитесь, что type диаграммы поддерживает заданные вами каналы. Секторные диаграммы (круговые и кольцевые) используют theta и color, а не x и y.
dct validate предупреждает о повторной агрегации — Запрос накопленной выручки намеренно суммирует уже агрегированный столбец, поэтому это предупреждение можно игнорировать. При этом dct validate завершается успешно.

Что дальше

Поздравляем 🎉! Вы собрали проект dbt локально, создали собственный каталог dbt Charts и файл панели, добавили пять визуализаций на основе моделей dbt и просмотрели панель в браузере.

Теперь вы можете:

Добавить интерактивность с помощью переменных, чтобы пользователи могли фильтровать данные по магазину или диапазону дат.
Изучить другие типы диаграмм, например наборы однотипных диаграмм, многослойные диаграммы и карты.
Добавить новые файлы в каталог charts/ — каждый из них станет отдельной страницей, поэтому большой дашборд можно разделить на тематические панели.
Построить диаграммы на основе других моделей dbt, добавив новые SQL-запросы, или изучить другие типы запросов, например значения и HTTP-источники.

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

Создать GitHub Issue

Краткое руководство по dbt Charts

Введение

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

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

Клонирование примера проекта и его сборка

Создание каталога charts и файла панели

Добавление первых пяти диаграмм

1. Линейная диаграмма: динамика выручки

2. Столбчатая диаграмма: выручка по магазинам

3. Диаграмма с областями: накопленная выручка

4. Круговая диаграмма: выручка по типам продуктов

5. Таблица: KPI магазинов

Размещение элементов панели

Установка dbt Charts и просмотр панели

Устранение неполадок

Что дальше

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

Начните работать с dbt.

Ресурсы dbt

Продукты

Сообщество

Поддержка

Наши соцсети

Введение​

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

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

Клонирование примера проекта и его сборка​

Создание каталога charts и файла панели​

Добавление первых пяти диаграмм​

1. Линейная диаграмма: динамика выручки​

2. Столбчатая диаграмма: выручка по магазинам​

3. Диаграмма с областями: накопленная выручка​

4. Круговая диаграмма: выручка по типам продуктов​

5. Таблица: KPI магазинов​

Размещение элементов панели​

Установка dbt Charts и просмотр панели​

Устранение неполадок​

Что дальше​

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

Ресурсы dbt

Продукты

Сообщество

Поддержка

Наши соцсети

Введение

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

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

Клонирование примера проекта и его сборка

Создание каталога charts и файла панели

Добавление первых пяти диаграмм

1. Линейная диаграмма: динамика выручки

2. Столбчатая диаграмма: выручка по магазинам

3. Диаграмма с областями: накопленная выручка

4. Круговая диаграмма: выручка по типам продуктов

5. Таблица: KPI магазинов

Размещение элементов панели

Установка dbt Charts и просмотр панели

Устранение неполадок

Что дальше