# Как использовать промпты для dbt Wizard

[Назад к гайдам](https://docs.getdbt.tech/guides.md)

[Menu ]()



## Обзор

Узнайте, как писать эффективные промпты для dbt dbt Wizard, чтобы генерировать корректный SQL-код, модели, метрики и макросы. Каждый рецепт самодостаточен и содержит собственный реалистичный пример.

dbt dbt Wizard — это ИИ-ассистент, который генерирует SQL, YAML, документацию, тесты, семантические модели и макросы с учетом контекста вашего проекта. Качество результата зависит от того, насколько ясно сформулированы ваши промпты.

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

В сборнике рассматриваются следующие темы:

* [Рекомендации по написанию промптов](https://docs.getdbt.com/guides/prompt-cookbook?step=2)
* [Генерация SQL-запросов](https://docs.getdbt.com/guides/prompt-cookbook?step=3)
* [Использование имеющихся материалов](https://docs.getdbt.com/guides/prompt-cookbook?step=4)
* [Создание семантических моделей и метрик](https://docs.getdbt.com/guides/prompt-cookbook?step=5)
* [Создание переиспользуемых макросов](https://docs.getdbt.com/guides/prompt-cookbook?step=6)
* [Устранение ошибок и проблем](https://docs.getdbt.com/guides/prompt-cookbook?step=7)
* [Заключение](https://docs.getdbt.com/guides/prompt-cookbook?step=8)

## Рекомендации по написанию промптов

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

* [Предоставляйте подробный контекст](#provide-rich-context)
* [Разбивайте сложную логику на небольшие шаги](#break-complex-logic-into-smaller-steps)
* [Формулируйте бизнес-вопрос, а не только желаемый результат](#state-the-business-question-not-just-the-output)
* [Четко и явно описывайте результат](#be-clear-and-explicit-about-the-result)

### Предоставляйте подробный контекст

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

Включайте следующее:

* Связи между таблицами (например, `orders` связана с `customers` по `customer_id`)
* Типы данных (например, `signup_date` имеет тип timestamp)
* Примеры значений (например, `plan_type` может принимать значения "monthly" или "annual")

подсказка

В следующем примере используется терминология SQL (например, типы данных и соединения), поскольку задача — сгенерировать SQL-запрос. Однако принцип предоставления подробного контекста применим ко всем задачам dbt Wizard: генерации макросов, документации или конфигураций YAML.

**Пример: кафе Санти по соседству**

Допустим, вы управляете небольшим кафе, где после 10 посещений гости получают бесплатный напиток:

**Без подробного контекста** (расплывчато):

```text
Мне нужен запрос к таблицам customers, subscriptions и activity, чтобы определить постоянных гостей, которые приходят каждую неделю.
```

**С подробным контекстом** (конкретно):

```text
Контекст: я веду программу лояльности кафе, в которой гости получают бесплатный напиток после 10 посещений.

Таблицы и связи:

- customers (customer_id INT or integer, name STRING, email STRING, signup_date TIMESTAMP)
- subscriptions (subscription_id INT, customer_id INT, plan_type STRING, start_date DATE, end_date DATE)
  - Соединяется с customers по customer_id
  - Значения plan_type: "monthly", "annual", null для гостей без подписки
- activity (activity_id INT, customer_id INT, visit_date DATE, visit_count INT)
  - Соединяется с customers по customer_id
  - visit_count отслеживает накопленное число посещений (сбрасывается после получения бесплатного напитка)

Бизнес-вопрос: покажи, какие гости приходят каждую неделю (3+ раза в неделю на протяжении 4+ недель), 
и сравни показатели конверсии: оформляют ли активные участники программы лояльности 
подписку «кофейные зерна месяца» чаще, чем нерегулярные посетители?
```

**Почему это работает:** теперь ИИ знает точные типы данных, связи между таблицами, ожидаемые значения и конкретную бизнес-логику (3+ посещения в неделю определяют «постоянных гостей»).

### Разбивайте сложную логику на небольшие шаги

Распространенное заблуждение

Многие пользователи пытаются запросить все сразу в одном промпте. Разбиение запроса на небольшие последовательные шаги стабильно дает лучшие результаты.

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

**Пример:**

```text
1. Отфильтруй набор данных, оставив пользователей, активных за последние 90 дней.
2. Рассчитай среднюю продолжительность их сеансов.
3. Соедини результат с данными о подписках и сгруппируй по уровню тарифного плана.
```

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

### Формулируйте бизнес-вопрос, а не только желаемый результат

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

**Пример: выпуск новой коллекции кроссовок**

Допустим, у вас интернет-магазин кроссовок и вы только что запустили новую функцию: перед покупкой клиенты могут просматривать кроссовки в 3D.

```text
Одновременно с последним выпуском лимитированной коллекции кроссовок мы запустили функцию 3D-просмотра. 
Была ли конверсия в покупку у клиентов, использовавших 3D-просмотр, выше, чем 
у тех, кто смотрел только фотографии?

Покажи недельные показатели конверсии посетителей в покупателей с разбивкой по тому, 
использовали ли они 3D-просмотр. Если конверсия у пользователей 3D-просмотра выше на 20% или более, мы добавим 3D 
для всех товаров. Если нет, мы улучшим функцию, прежде чем расширять ее использование.
```

**Почему это работает:** вы описали функцию, поведение, которое измеряете, конкретные критерии успеха (рост на 20% или более) и решение, которое примете на основе результатов.

### Четко и явно описывайте результат

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

**Что следует указать:**

* Ожидаемые имена столбцов и форматы
* Порядок сортировки и ограничения (например, «10 лучших товаров по выручке»)
* Примеры формата результата (например, «`conversion_rate` в процентах»)

**Пример: фитнес-челлендж**

В этом примере вы управляете фитнес-приложением с двухнедельным челленджем — тренировками с гирей от Кимико.

```text
Покажи недельную динамику: дату, число активных участников и простой показатель «вовлеченность на человека». 
Затем сделай сводку по неделе запуска с показателями «начало пробного периода», «переход на платный тариф за 30 дней» 
и «доля переходов на платный тариф» в процентах.

Для каждой недели покажи число активных участников челленджа и общее число тренировок. По неделе начала челленджа 
покажи, сколько участников перешли на платный тариф в течение 30 дней и каково было среднее число их тренировок.
```

**Почему это работает:** заданы конкретные метрики, готовые к представлению.

## Генерация SQL-запросов

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

```text
Контекст:
У меня есть две таблицы:
- customers (customer_id, name, email)
- orders (order_id, customer_id, order_total, order_date)

Связь: orders.customer_id связана с customers.customer_id

Бизнес-вопрос:
Покажи 10 клиентов с наибольшей общей суммой покупок за 2024 год.

Результат:
- customer_id
- customer_name
- total_spent
- order_count

Отсортируй по total_spent по убыванию, ограничь результат 10 строками.
```

**Что генерирует dbt Wizard:**

```sql
select
    c.customer_id,
    c.name as customer_name,
    sum(o.order_total) as total_spent,
    count(o.order_id) as order_count
from {{ ref('customers') }} c
inner join {{ ref('orders') }} o
    on c.customer_id = o.customer_id
where year(o.order_date) = 2024
group by c.customer_id, c.name
order by total_spent desc
limit 10
```

**Почему это работает:**

* Понятный контекст о таблицах и связи между ними
* Конкретный бизнес-вопрос с определенным временным периодом
* Явные требования к результату и логике сортировки

**Совет от экспертов:** начните с простого, затем дорабатывайте. Если первая попытка dbt Wizard неидеальна, ничего страшного! Уточните промпт, добавив конкретные детали, и дайте dbt Wizard проявить себя — обычно в итоге он справляется ✨

## Использование имеющихся материалов

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

Интеграция с dbt Insights

При использовании dbt Wizard в [Insights](https://docs.getdbt.tech/docs/explore/dbt-insights.md) вы можете легко сопоставлять SQL, сгенерированный dbt Wizard, с метаданными из [dbt Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md). Эта встроенная интеграция обеспечивает удобный доступ к документации, определениям и примерам данных при создании запросов.

### Определите бизнес-правила

Вместо того чтобы просто сказать «активный клиент», объясните правило:

```text
Активный клиент = хотя бы одна оплаченная покупка за последние 90 дней, исключая возвраты
Чистая выручка = валовые продажи за вычетом скидок и возвратов
```

**Где взять:** глоссарии метрик, каталоги KPI, документы с требованиями к продукту, словари данных

### Покажите примеры значений

Дайте dbt Wizard примеры того, как на самом деле выглядят данные, особенно в граничных случаях:

```text
Статусы заказов:
- `customer_id: C-12, created_at: 2025-05-03T09:07:00Z, status: 'completed'`
- `customer_id: C-14, created_at: 2025-05-03T09:02:00Z, status: 'cancelled'`
- `customer_id: C-13, created_at: 2020-01-02T06:40:00Z, status: 'pending'`
```

**Где взять:** отчеты о профилировании данных, тестовые наборы данных QA, фильтры BI-дашбордов

### Начните с черновика, доработайте позже

Сначала наметьте модель, затем дорабатывайте ее. Начните с простого наброска, который правильно задает базовую структуру:

```text
На основе stg_orders и dim_customers создай минимальную модель с order_id, customer_id, 
order_date, net_revenue = gross - coalesce(discount, 0) и соединением с dim_customers 
по customer_id. Только для предварительного просмотра отфильтруй данные за последние 30 дней.
```

**Где взять:** таблицы сопоставления источников и целевых данных (ключи соединения и преобразования), словари данных (первичные и внешние ключи)

## Создание семантических моделей и метрик

Ускорьте реализацию стратегии семантического слоя с помощью YAML, сгенерированного ИИ в dbt Wizard.

dbt platform предоставляет встроенные кнопки генерации, которые позволяют автоматически [генерировать код](https://docs.getdbt.tech/docs/dbt-ai/wizard-ide.md), [документацию](https://docs.getdbt.tech/docs/build/documentation.md), [тесты данных](https://docs.getdbt.tech/docs/build/data-tests.md), [метрики](https://docs.getdbt.tech/docs/build/metrics-overview.md) и [семантические модели](https://docs.getdbt.tech/docs/build/semantic-models.md) одним нажатием в [Studio IDE](https://docs.getdbt.tech/docs/platform/studio-ide/develop-studio-ai.md) и [Insights](https://docs.getdbt.tech/docs/explore/dbt-insights.md).

Эти функции учитывают структуру вашей модели и генерируют YAML в нужном месте.

**Как сгенерировать семантические модели:**

1. Перейдите в Studio IDE и выберите файл SQL-модели в **File explorer**
2. В разделе **Console** (под **Editor**) нажмите значок **dbt Wizard**, чтобы открыть доступные действия с ИИ
3. Выберите **Semantic model**, чтобы создать семантическую модель на основе вашей SQL-модели
4. Проверьте и при необходимости доработайте сгенерированный YAML

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

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

**Типичный рабочий процесс:**

1. Создайте SQL-модель, используя диалоговые промпты для dbt Wizard
2. Используйте встроенные кнопки, чтобы добавить документацию, тесты и семантические модели
3. При необходимости доработайте сгенерированный YAML

Подробнее см. в документации [dbt Wizard](https://docs.getdbt.tech/docs/dbt-ai/wizard-ide.md).

## Создание переиспользуемых макросов

В этом разделе мы рассмотрим, как создавать переиспользуемые макросы с помощью dbt Wizard.

* [Превращайте повторяющийся код в переиспользуемую логику](#turn-repetitive-code-into-reusable-logic)
* [Снижайте порог входа](#lower-the-barrier-to-entry)
* [Ускоряйте разработку сложной логики](#accelerate-complex-logic-design)

### Превращайте повторяющийся код в переиспользуемую логику

Начинающий аналитик постоянно копирует выражения CASE из одной модели в другую.

**Что передать dbt Wizard:**

```text
Преобразуй этот шаблон CASE в переиспользуемый макрос:

CASE 
  WHEN amount >= 1000 THEN 'high'
  WHEN amount >= 500 THEN 'medium'
  ELSE 'low'
END

Требования к макросу:
- Имя: categorize_amount
- Параметры: имя столбца, верхний порог (по умолчанию 1000), средний порог (по умолчанию 500)
- Добавь строку документации с примером использования
- Обрабатывай значения null, возвращая 'unknown'
```

**Почему это работает:** четкие входные данные (выражение CASE), четкие требования и четкие ожидания от результата.

### Снижайте порог входа

Вам нужен макрос, но вы плохо знаете синтаксис Jinja.

**Что спросить у dbt Wizard:**

```text
Мне нужен макрос, который вычисляет число дней между двумя столбцами с датами, 
исключая выходные.

Параметры:
- start_date_column (обязательный)
- end_date_column (обязательный)

Добавь строку документации с объяснением использования.
```

**Результат:** dbt Wizard генерирует корректный синтаксис Jinja, обрабатывает параметры и добавляет документацию. Вы изучаете приемы Jinja и одновременно получаете рабочий код.

### Ускоряйте разработку сложной логики

Этот подход лучше всего подходит опытным пользователям, уверенно работающим с Jinja.

**Что спросить у dbt Wizard:**

```text
Мне нужен макрос, который строит агрегацию с группировкой и необязательными фильтрами.

Параметры:
- relation (модель/таблица для запроса)
- group_by (список столбцов для группировки)
- metrics (список столбцов для агрегации)
- where (необязательное условие фильтрации)

Добавь значения по умолчанию и защиту от пустых списков.
Добавь строку документации с описанием параметров и примером использования.
```

**Почему это работает:** вы описали интерфейс (параметры) и граничные случаи (пустые списки), позволив dbt Wizard подготовить шаблонный код Jinja, пока вы сосредоточены на проектировании. Такой подход ускоряет итерации: вы можете дорабатывать структуру, не застревая на деталях синтаксиса.

## Устранение ошибок и проблем

dbt Wizard помогает быстро проверять SQL и макросы, которые завершаются с ошибками, учитывая контекст. Он читает сообщения об ошибках, анализирует структуру запроса и предлагает минимальные исправления. Устранение неполадок с помощью dbt Wizard дает вам:

* Более быструю диагностику благодаря объяснению ошибок простым языком с указанием вероятных первопричин
* Более безопасные исправления благодаря предпочтению небольших, точечных изменений
* Лучшее понимание благодаря объяснениям, которые можно вставить в документацию или описания PR

### Устранение ошибок

Когда что-то ломается, передайте dbt Wizard сообщение об ошибке, свой код и описание ожидаемого поведения. Вот несколько примеров того, как использовать dbt Wizard для устранения ошибок.

**Пример: ошибка SQL**

```text
Ошибка: "SQL compilation error: Column 'product_name' must appear in GROUP BY"

Запрос:
SELECT 
  product_id,
  product_name,
  SUM(quantity) as total_quantity
FROM inventory
GROUP BY product_id

Хранилище данных: Snowflake
Ожидаемый результат: сгруппировать по товару и показать название товара. Что не так и как это исправить?
```

**Пример: макрос не работает**

```text
Этот макрос должен вычислять скидку, но возвращает неверные значения:

{% macro calculate_discount(amount, rate) %}
  {{ amount }} * {{ rate }}
{% endmacro %}

При вызове {{ calculate_discount(100, 0.1) }} я ожидаю получить 10, но получаю ошибку.
Покажи сгенерированный SQL из target/compiled и объясни, что не так.
```

**Совет:** указывайте тип вашего хранилища данных (Snowflake, BigQuery, Databricks и т. д.) — синтаксис может различаться между платформами данных.

## Заключение

Поздравляем! Теперь вы знаете несколько приемов создания и использования промптов для dbt dbt Wizard 🎉! Вы можете:

* Улучшать навыки написания промптов, предоставляя подробный контекст и формулируя четкие бизнес-вопросы. Это применимо к SQL, макросам, документации, тестам, метрикам и семантическим моделям.
* Делать рабочий процесс эффективнее, используя существующую документацию и контекст проекта
* Генерировать макросы Jinja для создания более масштабируемых и удобных в сопровождении систем
* Находить ошибки в коде, чтобы быстро диагностировать проблемы и применять безопасные, понятные исправления

### Краткий контрольный список

При написании промптов для dbt dbt Wizard:

* ✅ Предоставляйте подробный контекст: имена таблиц, столбцы, типы данных, связи, примеры значений
* ✅ Разбивайте сложную логику: представляйте составные запросы как последовательность шагов
* ✅ Формулируйте бизнес-вопрос: какое решение или аналитический вывод вам нужен, а не просто «напиши запрос»
* ✅ Пишите четко и явно: указывайте ожидаемые столбцы, порядок сортировки, фильтры и формат результата

При устранении неполадок:

* ✅ Приводите полные сообщения об ошибках: полный текст ошибки хранилища данных с номерами строк
* ✅ Показывайте проблемный код: и модель dbt, и скомпилированный SQL (из `target/compiled/`)
* ✅ Предоставляйте примеры данных: характерные строки, которые вызывают проблему
* ✅ Указывайте хранилище данных: Snowflake, BigQuery, Databricks и т. д.

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

Начните с одной задачи — автоматизации документации, генерации теста или рефакторинга модели — и постепенно сделайте это привычкой.

Чем больше вы используете dbt Wizard, тем больше способов ускорить рабочий процесс аналитической инженерии вы найдете.

Ознакомьтесь со следующей документацией, чтобы узнать больше об использовании dbt Wizard:

* [О dbt Wizard](https://docs.getdbt.tech/docs/platform/wizard-platform.md)
* [dbt Wizard в Studio IDE](https://docs.getdbt.tech/docs/dbt-ai/wizard-ide.md)
* [Генерация ресурсов](https://docs.getdbt.tech/docs/dbt-ai/wizard-ide.md#panel-controls)
* [Создание визуальных моделей с dbt Wizard](https://docs.getdbt.tech/docs/platform/build-canvas-copilot.md)
* [Создание запросов в dbt Insights](https://docs.getdbt.tech/docs/explore/navigate-dbt-insights.md)