Как работает dbt Wizard
dbt Wizard помогает командам быстрее разрабатывать, отлаживать, повышать надёжность и выпускать проверенные проекты dbt с меньшими рисками.
Созданный для разработки данных с централизованным управлением в dbt, dbt Wizard понимает ваш проект, обращается к нужным инструментам dbt и проверяет результаты с учётом операций в хранилище данных. Используйте его для анализа неудачных запусков, отладки моделей, оценки влияния, внесения изменений и выпуска проверенных решений для работы с данными — всё в одном месте.
Большинство принципов работы dbt Wizard одинаковы в dbt platform, Wizard Desktop и CLI в терминале. В следующих разделах сначала описано общее поведение, а затем — различия между средами.
dbt Information Schema
dbt Wizard использует dbt Information Schema — интерфейс к метаданным вашего проекта с определённым контрактом, который готов к работе ещё до вашего первого запроса.
Представьте себе карту всего города: dbt Wizard ещё до начала работы знает, как всё связано, вместо того чтобы обходить каждую улицу для изучения планировки. ( не нужен.)
Эти метаданные дают dbt Wizard четыре возможности, которые нельзя получить одним лишь чтением файлов:
| Возможность | Описание |
|---|---|
| Анализ влияния | Когда вы спрашиваете «что сломается, если я изменю этот столбец?», dbt Wizard мгновенно возвращает из dbt Information Schema точный набор затронутых нижестоящих моделей, метрик, тестов и exposures. Происхождение данных отслеживается на уровне столбцов, поэтому dbt Wizard знает не только, какие модели ссылаются на таблицу, но и какие из них ссылаются на конкретный столбец. |
| Проверки состояния | dbt Wizard располагает структурированным набором данных о том, у каких моделей есть тесты, у каких их нет, в каких данные устарели, какие нарушают контракты и у каких недавно были неудачные запуски. Вы можете спросить «какие проблемы есть в этой части моего DAG?» и получить точный ответ, ничего не запуская. |
| Профилирование данных | dbt Wizard может профилировать ваши данные — определять количество строк, распределения значений столбцов, долю null — и учитывать этот контекст при выборе способа построения или рефакторинга модели. Он может анализировать ваши данные без материализации моделей и выполнения дорогостоящих запросов. |
| Планирование валидации | dbt Wizard использует метаданные проекта, чтобы определить затронутые ресурсы и выбрать подходящие проверки. В CLI вы управляете глубиной структурированной валидации до выполнения команд. |
dbt Wizard создаёт и обновляет эти метаданные на основе артефактов dbt. В dbt platform состояние проекта поступает из подключённой среды разработки. В терминале запустите dbt parse, dbt compile или dbt build перед началом сеанса, чтобы dbt Wizard располагал актуальным состоянием локального проекта.
Версия dbt, которую отображает dbt Wizard, берётся из манифеста вашего проекта (target/manifest.json), а не из исполняемого файла dbt в вашем PATH. Если вы создали манифест с помощью другого исполняемого файла, dbt Wizard будет показывать ту версию до повторной компиляции. Выполните dbt compile (или dbt parse/dbt build) с нужной версией dbt, чтобы обновить манифест и отображаемую версию.
Механика валидации
Валидация может сочетать статические проверки, команды dbt, сборки в среде разработки, анализ влияния на нижестоящие ресурсы и сравнение среды разработки с продуктивной средой. Выполняемые проверки зависят от интерфейса, доступных инструментов, состояния проекта, разрешений и одобренной вами глубины валидации.
В dbt Wizard CLI или Wizard Desktop выберите лёгкую, среднюю, глубокую валидацию или её пропуск. По умолчанию используется средняя валидация:
- Лёгкая валидация сосредоточена на синтаксисе, линтинге там, где он поддерживается, тестах и проверке кода без материализации изменённых моделей.
- Средняя валидация дополнительно включает материализацию в среде разработки и проверки нижестоящих ресурсов.
- Глубокая валидация дополнительно включает явно заданные ожидаемые результаты и сравнение среды разработки с продуктивной средой, когда доступны необходимые отношения.
dbt Wizard сообщает об ошибках и проверках, которые не удалось выполнить. Успешная проверка не отменяет необходимости проверить бизнес-логику, а пропущенная проверка должна оставаться видимой при ревью. Полную процедуру и этапы согласования команд для хранилища данных см. в разделе Валидация изменений dbt с помощью dbt Wizard.
Инструменты и возможности
dbt Wizard выполняет действия с помощью определённого набора инструментов — от чтения файлов до запуска команд dbt, — поэтому вы можете точно видеть, что он делает и почему.
| Инструмент | Назначение | Где доступен |
|---|---|---|
| Чтение и запись файлов | Чтение файлов и предложение правок в виде diff | Платформа, CLI и Desktop |
| Запросы к проекту | Запросы к графу зависимостей, тестам, метаданным, метрикам и результатам запусков | Платформа, CLI и Desktop |
| Команды dbt | Выполнение команд, таких как dbt compile, dbt build и dbt test | Платформа, CLI и Desktop |
| Bash | Выполнение команд оболочки в каталоге проекта | CLI и Desktop |
| Поиск в интернете | Поиск документации dbt и информации об устранении неполадок | Платформа, CLI и Desktop |
| MCP | Доступ к подключённым MCP-серверам | CLI и Desktop (добавление серверов); платформа включает встроенную документацию и контекст платформы |
dbt Wizard никогда не выполняет потенциально разрушительные команды (такие как dbt build --full-refresh, dbt run --full-refresh или git reset --hard) без одобрения.
Навыки и память
dbt Wizard поддерживает многократно используемые навыки и память, которые помогают ему применять принятые в вашей команде соглашения в разных сеансах.
| Функция | Описание |
|---|---|
| Навыки | Стандартизируют повторяющиеся рабочие процессы и лучшие практики. Например, навык может объяснять dbt Wizard, как ваша команда структурирует staging-модели, пишет тесты или документирует столбцы. |
| Память | Хранит контекст конкретного проекта, который должен сохраняться между сеансами. Например, dbt Wizard может запомнить, что в вашем проекте customer_id используется как стандартный ключ клиента или что финансовые модели требуют дополнительной проверки. |
dbt Wizard автоматически загружает навыки из каталогов проекта и локальных каталогов как на платформе, так и в CLI. На платформе после добавления или изменения навыков начните новый чат, чтобы они были подхвачены.
Подробнее см. на странице Навыки.
В dbt platform
Используйте dbt Wizard в dbt platform из главного приложения или Studio IDE.
Как передаются данные при работе dbt Wizard на платформе dbt и какие данные передаются и не передаются провайдеру ИИ.Ваш запрос, метаданные проекта и результаты запросов, передачу которых вы одобрили, отправляются провайдеру ИИ по протоколу TLS. Учетные данные хранилища данных не передаются, запросы выполняются только после вашего одобрения, а провайдеры, управляемые dbt Labs, не могут хранить ваши данные на постоянной основе или использовать их для обучения моделей.
Согласование и проверка
По умолчанию dbt Wizard оставляет вам контроль перед изменением проекта или выполнением команд.
На платформе:
- dbt Wizard показывает правки файлов в виде diff, чтобы вы могли принять или отклонить их до сохранения
- Команды dbt запрашивают подтверждение перед выполнением
- В главном приложении и Studio IDE переключайтесь между Ask for approval и Edit files automatically, чтобы выбрать степень свободы агента для каждого сеанса
На платформе нет изолированной среды bash — доступ к оболочке не предоставляется так, как в CLI.
Сеансы и диалоги
На платформе сеанс — это сохранённый диалог на панели dbt Wizard или в главном приложении:
- Задавайте уточняющие вопросы без повторного изложения всего контекста
- Продолжайте ранее начатый анализ, рефакторинг или валидацию
- Просматривайте предыдущие запросы, ответы и предложенные изменения в списке диалогов
Начните новый сеанс с помощью Start new dbt Wizard chat на панели. История чата хранится 90 дней. Обновление той же вкладки браузера сохраняет активный сеанс; новая вкладка открывается без активного диалога.
Используйте отдельный чат для каждой самостоятельной задачи, например построения одной модели, отладки одного сбоя задания или проверки изменения. Сфокусированный диалог сохраняет контекст, относящийся к задаче, чтобы dbt Wizard не переносил предположения из несвязанной работы. Возвращайтесь к существующему чату, только если продолжаете ту же задачу.
Особенности работы и доступность в Studio описаны в разделе dbt Wizard в Studio IDE.
Локально (CLI и Desktop)
Используйте dbt Wizard CLI или Wizard Desktop для локальной разработки. Всё в этом разделе относится к обоим вариантам, поскольку приложение использует тот же движок, что и CLI.
Подключения и аутентификация (MCP)
dbt Wizard может подключаться к MCP-серверам из CLI, включая dbt MCP server, для доступа к API платформы, метаданным Semantic Layer и контексту разных проектов. Полную информацию о настройке (например, поддерживаемые типы серверов, ключи конфигурации, аутентификацию и примеры) см. в разделе Использование MCP-серверов с dbt Wizard CLI. Поддержка MCP-коннекторов в Wizard Desktop появится в ближайшее время.
Чтобы подключиться к MCP-серверу, выполните следующие команды, заменив MCP_NAME выбранным вами именем, а YOUR_MCP_URL — URL-адресом MCP-сервера:
wizard mcp add MCP_NAME --url https://YOUR_MCP_URL
wizard mcp login MCP_NAME
Дополнительные параметры можно посмотреть, выполнив wizard mcp --help.
Например, чтобы подключиться к dbt MCP server, замените DBT_MCP_ENDPOINT адресом вашей конечной точки и выполните:
wizard mcp add dbt --url DBT_MCP_ENDPOINT
Вы должны увидеть вывод, похожий на Added global MCP server 'dbt'. Затем выполните аутентификацию:
wizard mcp login dbt
dbt MCP server считывает настройки подключения — такие как DBT_HOST, DBT_TOKEN, DBT_PROJECT_DIR, DBT_PATH, DBT_PROD_ENV_ID и DBT_ACCOUNT_ID — из переменных окружения, обычно из файла .env в корне вашего проекта dbt.
Если dbt Wizard не может подключиться к серверу, убедитесь, что эти значения заданы, а затем перезапустите wizard, чтобы он подхватил изменения.
Полный список переменных и пример файла .env см. в разделах Настройка самостоятельно размещаемого MCP и Справочник переменных окружения.
Отложенное разрешение ссылок и состояние
Когда вы работаете над частью проекта, dbt Wizard использует отложенное разрешение ссылок (deferral), чтобы повторно использовать модели, уже построенные в другой среде (например, в продуктивной), вместо повторного построения всего проекта. Это экономит время и снижает затраты на хранилище данных.
Способ обработки отложенного разрешения ссылок зависит от режима, заданного для вашего проекта в wizard_config.toml:
Значение deferral.mode | Поведение |
|---|---|
"wizard" | dbt Wizard управляет отложенным разрешением ссылок за вас. Вы указываете dbt Wizard, какой target из profiles.yml использовать для отложенного разрешения ссылок (при первоначальной настройке проекта он пытается определить его автоматически). Затем dbt Wizard компилирует этот target и повторно использует его модели вместо вышестоящих моделей, которые вы ещё не построили самостоятельно. |
"fusion_cloud" | dbt platform обрабатывает отложенное разрешение ссылок с использованием подключённой среды, поэтому dbt Wizard не управляет локальным состоянием. |
"cloud_cli" | dbt platform CLI управляет учётными данными и отложенным разрешением ссылок через dbt platform, поэтому dbt Wizard не управляет локальным состоянием и не добавляет флаги отложенного разрешения ссылок. |
"dbt_state" | dbt State или кеш запусков обрабатывает отложенное разрешение ссылок, поэтому dbt Wizard пропускает собственную компиляцию для продуктивной среды. |
"manual" | Вы вручную поддерживаете путь к манифесту для отложенного разрешения ссылок. |
"disabled" | Отложенное разрешение ссылок отключено для проекта. |
Подробнее о dbt State см. в разделе О dbt State.
Параметр favor_state, задаваемый для каждого проекта, по умолчанию имеет значение true. Когда favor-state включён, отношения из среды отложенного разрешения ссылок имеют приоритет. Установите favor_state = false, если хотите, чтобы dbt использовал отношения, уже построенные вами в среде разработки, и обращался к среде отложенного разрешения ссылок только для отношений, отсутствующих в среде разработки.
dbt Wizard хранит режим отложенного разрешения ссылок для каждого проекта в wizard_config.toml в параметре deferral.mode. Полную процедуру настройки и проверки см. в разделе Разработка с отложенным разрешением ссылок на продуктивную среду.
Согласование и изоляция
По умолчанию CLI оставляет вам контроль перед изменением проекта или выполнением команд.
В терминале:
- dbt Wizard показывает изменения файлов в виде diff, чтобы вы могли их проверить
- Команды, требующие разрешения согласно действующей политике согласования, запрашивают подтверждение перед выполнением
- Активный профиль изоляции ограничивает области, в которых команды оболочки могут читать и записывать данные. dbt Wizard показывает активный профиль при запуске сеанса.
Выберите профиль изоляции и режим согласования, соответствующие задаче:
# Ограничить команды оболочки доступом только для чтения.
wizard --sandbox read-only
# Никогда не запрашивать одобрение в течение этого сеанса.
# Полезно для доверенных задач, в которых Wizard должен работать итеративно без остановок.
wizard --ask-for-approval never
# Разрешить командам оболочки запись в каталоге вашего рабочего пространства.
# Полезно для команд, создающих файлы.
wizard --sandbox workspace-write
Используйте менее строгие настройки, если хотите, чтобы dbt Wizard быстрее выполнял ограниченную задачу, которой вы доверяете, например масштабный рефакторинг, создание документации или однотипные обновления тестов. Компромисс в том, что dbt Wizard получает больше свободы действий до проверки вами каждого шага, поэтому используйте эти настройки в чистом рабочем дереве или отдельной ветке для изменений.
Настройки согласования применяются к текущему сеансу. Показанные выше флаги командной строки не позволяют ограничить их отдельными типами действий; например, --ask-for-approval never отменяет запросы подтверждения в целом для этого сеанса. Чтобы задать значения по умолчанию, сохраняющиеся между сеансами или применяемые только к определённому проекту, используйте файл конфигурации.
Дополнительные параметры можно посмотреть, выполнив:
wizard --help
Сеансы
При локальной работе сеанс — это сохранённый диалог и история задач из предыдущего запуска на вашем компьютере. Сеансы помогают вернуться к предыдущей работе, продолжить многоэтапную задачу или проверить, что агент делал при прошлом взаимодействии.
В рамках сеанса вы можете:
- Задавать уточняющие вопросы без повторного изложения всего контекста
- Продолжать ранее начатый анализ, рефакторинг или валидацию
- Просматривать предыдущие запросы, ответы, вызовы инструментов и предложенные изменения
Возобновите предыдущий сеанс с помощью:
wizard resume # выбрать из списка сохранённых сеансов
wizard resume --last # возобновить последний сеанс
Локальные сеансы сохраняются на вашем компьютере как в CLI, так и в Wizard Desktop. Они отделены от диалогов на платформе, которые хранятся в вашей учётной записи dbt platform.
Используйте отдельный сеанс для каждой самостоятельной задачи, например построения одной модели, отладки одного сбоя задания или проверки одного изменения. Возобновляйте предыдущий сеанс, только если продолжаете ту же задачу. В CLI введите /new, чтобы начать заново, не выходя из TUI, или /compact, чтобы создать краткое изложение диалога, если длительный сеанс по одной задаче приближается к пределу контекста. Подробнее см. в разделе Слеш-команды.
Связанная документация
- Обзор dbt Wizard
- dbt Wizard в dbt platform
- Локальное использование dbt Wizard
- Справочник команд dbt Wizard
- Как использовать dbt Wizard в вашем проекте dbt — рекомендуемые рабочие процессы
