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

Быстрый старт с dbt v2

Назад к гайдам
dbt v2
Платформа dbt
Быстрый старт
Начальный уровень
Menu

    Введение​

    Важно

    dbt v2 доступен для установки в следующих средах:

    Присоединяйтесь к обсуждению в канале #dbt-v2 в Slack сообщества dbt.

    dbt v2 — это новый мощный подход к классическим идеям dbt! Полностью переписанный с нуля на Rust, dbt v2 позволяет компилировать и запускать проекты dbt быстрее, чем когда-либо, — зачастую за считаные секунды.

    Это руководство по быстрому старту поможет вам с нуля настроить и запустить свой первый проект dbt с помощью dbt v2 и VS Code. К концу руководства у вас будут:

    • Работающий проект dbt (jaffle_shop), созданный с помощью dbt v2
    • Установленное и подключённое расширение dbt для VS Code
    • Возможность просматривать результаты, компилировать проект и выполнять команды dbt прямо из IDE
    Follow along with an AI assistantCopy and paste this prompt into your AI assistant to guide you through each step

    О dbt v2​

    dbt v2 и предоставляемые им возможности доступны в нескольких средах:

    СредаКак использовать dbt v2
    Studio IDEdbt v2 включается автоматически; просто обновите свои среды.
    Локальный CLIУстановите dbt v2 локально, следуя этому руководству.
    VS Code / Cursor IDEУстановите расширение dbt, чтобы использовать интерактивные возможности dbt v2 в своём редакторе.

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

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

    Чтобы получить максимум от этого руководства, вам потребуется:

    Чтобы в полной мере воспользоваться этим руководством, необходимо выполнить следующие предварительные требования:

    • У вас должно быть базовое понимание проектов dbt, рабочих процессов git и требований к хранилищам данных.
    • Убедитесь, что вы используете поддерживаемый адаптер и метод аутентификации:
       BigQuery
       Databricks
      • Сервисный аккаунт / Токен пользователя
      • Встроенный OAuth
       Redshift
      • Имя пользователя / Пароль
      • Профиль IAM
       Snowflake
      • Имя пользователя / Пароль
      • Встроенный OAuth
      • Внешний OAuth
      • Пара ключей с использованием современного формата PKCS#8
      • MFA
       ClickHouseЗакрытая бета-версия
      • Имя пользователя / Пароль
       Apache Spark (только CLI)Бета-версия
      • Thrift
        • Простой уровень аутентификации и безопасности (SASL), механизм PLAIN
        • Без SASL (NOSASL)
      • Livy
        • Базовая аутентификация (имя пользователя и пароль)
        • При развертывании в Amazon Web Services (AWS): AWS Signature Version 4
          • Поддерживается аутентификация с использованием единого входа, сервисных учетных записей или пользовательских токенов
       DuckDB (только CLI)

      DuckDB не требует аутентификации — он работает локально на вашем компьютере.

      Обратите внимание, что жизненный цикл адаптера может различаться для dbt platform и локальной разработки. Адаптер может стать общедоступным (GA) в платформе dbt раньше, чем для локального использования.
    • Для запуска dbt v2 вам понадобится компьютер с macOS (Terminal), Linux или Windows (Powershell).
    • У вас должен быть установлен Visual Studio Code. Редактор кода Cursor также подойдёт, но инструкции в этом руководстве ориентированы на VS Code.
    • Вам необходимы права администратора или разрешение на установку программ на вашем компьютере.

    Чему вы научитесь​

    Следуя этому руководству, вы сможете:

    • Настроить полнофункциональную среду dbt с работающим проектом
    • Установить и использовать dbt v2 и расширение dbt для VS Code
    • Выполнять команды dbt из IDE или терминала
    • Просматривать данные и граф зависимостей, быстрее писать SQL с помощью автодополнения и многое другое!

    Дополнительные материалы доступны в виде качественных курсов и воркшопов dbt Learn.

    Установка​

    Легко представить dbt v2 и расширение dbt как два разных продукта, но вместе они образуют мощную комбинацию, которая раскрывает весь потенциал dbt. Думайте о dbt v2 именно как о движке. Расширение dbt и VS Code — это шасси, а вместе они образуют мощное средство для преобразования ваших данных.

    к сведению
    • Вы можете установить dbt v2 и использовать его отдельно через CLI.
    • Вы не можете использовать расширение dbt без установленного dbt v2.
    • Используйте dbt в качестве команды по умолчанию. Если у вас уже установлен другой инструмент командной строки dbt (например, dbt platform CLI или dbt v1), вы можете использовать dbtf как однозначный псевдоним для dbt v2.

    Ниже приведены основные шаги из руководств по установке dbt v2 и расширения:

    1. Выполните следующие команды, чтобы установить CLI dbt v2: 
      python -m pip install dbt

    Проверка установки dbt v2​

    1. После установки откройте новое окно командной строки и проверьте версию, чтобы убедиться, что dbt v2 установлен корректно. 
      dbt --version
    2. Вы должны увидеть вывод, похожий на следующий: 
      dbt 2.0.0

    Установка расширения dbt для VS Code​

    Расширение dbt для VS Code доступно в Visual Studio extension marketplace. Его можно установить прямо из редактора:

    1. Перейдите на вкладку Расширения в VS Code (или Cursor).
    2. Найдите dbt и выберите расширение от издателя dbt Labs, LLC.
      Поиск расширенияПоиск расширения
    3. Нажмите Установить.
    4. Когда появится соответствующий запрос, вы можете войти в учетную запись dbt platform или пропустить этот шаг. Чтобы вернуться к нему позже, воспользуйтесь инструкциями по входу в учетную запись или установке.
    5. Убедитесь, что расширение установлено: найдите надпись dbt Extension в строке состояния. Если она отображается, расширение успешно установлено!
      Проверка установки в строке состояния.Проверка установки в строке состояния.

    Инициализация проекта Jaffle Shop​

    1. Выполните dbt init в терминале из каталога, в котором хотите создать проект. Команда dbt init создаст пример проекта и поможет вам настроить профиль подключения.

      • Если у вас нет профиля подключения, который вы хотите использовать, запустите dbt init и следуйте подсказкам для настройки профиля:

      • Если у вас уже есть профиль подключения, который вы хотите использовать, укажите флаг --skip-profile-setup, а затем отредактируйте созданный файл dbt_project.yml, заменив profile: jaffle_shop на profile: <YOUR-PROFILE-NAME>.

        dbt init --skip-profile-setup
    • Если вы создали новые учетные данные с помощью интерактивных запросов, init автоматически запускает dbt debug в конце. Это позволяет убедиться, что созданный профиль обеспечивает корректное подключение к базе данных.

    1. Перейдите в каталог созданного проекта:

      cd jaffle_shop

    2. Соберите dbt‑проект (включая создание примерных данных):

      dbt build

    Просмотр метаданных в Catalog​

    Выполните dbt build --write-catalog локально, чтобы сгенерировать метаданные документации (команда dbt build без этого флага не генерирует метаданные документации). Чтобы просмотреть эти метаданные в Catalog, запустите задание в dbt platform, чтобы загрузить метаданные на платформу. Подробнее см. в разделе Поведение платформы.

    Это позволит:

    • Загрузить демонстрационные данные в ваше хранилище данных
    • Создать, построить и протестировать модели
    • Убедиться, что ваша среда dbt полностью работоспособна

    Изучение возможностей с расширением dbt для VS Code​

    Расширение dbt для VS Code (доступное для VS Code и Cursor) компилирует и собирает ваш проект с помощью dbt v2 — мощной и невероятно быстрой реализации dbt, созданной с нуля.

    Хотите увидеть dbt v2 в действии? Посмотрите следующее видео‑демо, чтобы понять, как это работает:

    Теперь, когда ваш проект работает, откройте его в VS Code или Cursor и посмотрите на dbt v2 в действии:

    1. Откройте меню View и нажмите Command Palette. Введите Workspaces: Add Folder to Workspace.
    2. Выберите папку jaffle_shop. Если вы не добавите корневую папку проекта dbt в рабочую область, языковой сервер dbt (LSP) не запустится. LSP обеспечивает такие возможности, как автодополнение, отображение информации при наведении и подсветка ошибок непосредственно в коде.
    3. Нажмите на логотип dbt на боковой панели, чтобы открыть панель Get started. Эта панель определяет ваше окружение и показывает следующий шаг настройки: установку исполняемого файла dbt v2, подтверждение того, что проект открыт, проверку совместимости с dbt v2 или регистрацию. Если вы ещё не перевели свой проект на dbt v2, прямо на панели можно выбрать Start with an agent (Copilot или Cursor) или Start manually in CLI. Подробности см. в разделе Начало работы.
    4. Откройте файл модели, чтобы посмотреть определение модели orders. Именно эту модель мы будем использовать во всех примерах ниже. 
          models/marts/orders.sql
    5. В нижней панели найдите Lineage и Query Results, а в правом верхнем углу — иконку dbt. Если всё это отображается, расширение установлено и работает корректно!
      Интерфейс VS Code с запущенным расширением.Интерфейс VS Code с запущенным расширением.

    Теперь вы готовы попробовать эти возможности на практике!

    Просмотр данных и кода​

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

    1. Найдите значок таблицы для команды Preview File в правом верхнем углу. Нажмите на него, чтобы просмотреть результаты на вкладке Query Results.

      Предварительный просмотр результатов запроса модели.Предварительный просмотр результатов запроса модели.

    2. Нажмите Preview CTE над orders as (, чтобы просмотреть результаты на вкладке Query Results.

      Предварительный просмотр результатов запроса CTE.Предварительный просмотр результатов запроса CTE.

    3. Найдите значок кода для команды Compile File между значками dbt и таблицы. При нажатии на этот значок открывается окно со скомпилированной версией модели.

      Значок команды Compile File.Значок команды Compile File.
      Результаты выполнения команды Compile File.Результаты выполнения команды Compile File.

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

    1. Откройте вкладку Lineage, чтобы увидеть lineage на уровне моделей.
      Визуализация lineage на уровне моделей.Визуализация lineage на уровне моделей.
    2. Откройте меню View, выберите Command Palette и введите dbt: Show Column Lineage, чтобы увидеть lineage на уровне колонок во вкладке Lineage.
      Показ lineage на уровне колонок.Показ lineage на уровне колонок.

    Использование понимания SQL​

    Пишите код умнее, а не сложнее. Автодополнение и контекстные подсказки помогают избегать ошибок и быстрее создавать корректный SQL.

    1. Чтобы увидеть Autocomplete в действии, удалите ref('stg_orders') и начните вводить ref(stg_, чтобы увидеть подходящие имена моделей. Используйте стрелки вверх и вниз, чтобы выбрать stg_orders.
      Автодополнение имени модели.Автодополнение имени модели.
    2. Наведите курсор на *, чтобы увидеть список выбираемых колонок и их типы данных.
      Наведение на * для просмотра имён колонок и типов данных.Наведение на * для просмотра имён колонок и типов данных.

    Ускорение стандартных dbt‑команд​

    Тестирование, тестирование… микрофон включён? Да — и он готов выполнять ваши команды с молниеносной скоростью! Когда нужно проверить код с помощью различных dbt‑команд:

    1. Иконка dbt в правом верхнем углу открывает список команд, доступных через расширение:
      Выберите команду через иконку dbt.Выберите команду через иконку dbt.
    2. Если открыть меню View, выбрать Command Palette и ввести >dbt:, вы увидите полный список доступных команд.
      Команды dbt в командной строке.Команды dbt в командной строке.

    Попробуйте выбрать некоторые из них и посмотрите, что они делают 😎

    Это только начало. Уже доступно гораздо больше возможностей, и ещё больше появится в будущем. Обязательно ознакомьтесь с нашими ресурсами, чтобы узнать всё о dbt v2 и расширении dbt для VS Code!

    Это только начало. Возможностей уже много, и впереди — ещё больше. Обязательно изучите наши материалы, чтобы узнать всё о dbt v2 и расширении dbt для VS Code!

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

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

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

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

     Как создать каталог .dbt в корневом каталоге и переместить файл dbt_cloud.yml

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

    • Директория .dbt — это скрытая папка в корне вашей файловой системы. Она используется для хранения конфигурационных файлов dbt. Префикс . делает папку скрытой, поэтому по умолчанию она не отображается в Finder или File Explorer.
    • Чтобы увидеть скрытые файлы и папки, нажмите Command + Shift + G на macOS или Ctrl + Shift + G на Windows. Это откроет диалог «Go to Folder», в котором можно перейти к директории .dbt.
    1. Клонируйте репозиторий вашего проекта dbt на локальный компьютер.
    2. Используйте команду mkdir, указав после неё имя папки, которую хотите создать.
    • Если вы используете macOS, добавьте префикс ~, чтобы создать папку .dbt в корне вашей файловой системы:
      • macOS: mkdir ~/.dbt
      • Windows: mkdir %USERPROFILE%\.dbt
     В Cursor не отображается вкладка lineage

    Если вы используете расширение dbt для VS Code в Cursor, вкладка lineage лучше всего работает в режиме Editor и не отображается в режиме Agent. Если вы находитесь в режиме Agent и вкладка lineage не отображается, просто переключитесь в режим Editor, чтобы просмотреть происхождение данных на уровне таблиц и столбцов вашего проекта.

     Расширение зависает в состоянии загрузки

    Если расширение пытается активироваться при запуске и остается в состоянии бесконечной загрузки, убедитесь, что:

    • У вас установлена последняя версия расширения dbt для VS Code.
    • У вас установлена последняя версия IDE.
    • У вас настроен корректный файл dbt_cloud.yml, который находится в правильном расположении.

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

    • Удалите файл dbt_cloud.yml и скачайте его заново.
    • Удалите и переустановите расширение dbt для VS Code.
     Настройки платформы dbt

    Если вы используете облачную платформу dbt, у вас есть настройка dbt-cloud: в файле dbt_project.yml и вы также используете dbt Mesh, необходимо указать идентификатор проекта:

    dbt-cloud:
    project-id: 12345 # Required

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

     Расширение dbt не активируется

    Если расширение dbt успешно активировано, в строке состояния в левом нижнем углу редактора появится надпись dbt Extension. Чтобы просмотреть диагностическую информацию о расширении dbt, нажмите кнопку dbt Extension.

    Если надпись dbt Extension отсутствует, скорее всего, расширение dbt не было установлено успешно. В этом случае попробуйте удалить расширение, перезапустить редактор, а затем установить расширение заново.

    Примечание: В VS Code можно скрывать элементы строки состояния. Проверьте, не скрыта ли надпись dbt Extension: для этого щелкните правой кнопкой мыши по строке состояния в редакторе. Если в контекстном меню есть пункт dbt Extension, значит, расширение установлено успешно.

     Недоступны функции dbt LSP

    Если вы получаете сообщение об ошибке no active LSP for this workspace или в редакторе недоступны функции языкового сервера dbt (LSP), такие как автодополнение, переход к определению или подсказки при наведении, сначала выполните общие действия по устранению неполадок, описанные выше.

    Если вы убедились, что расширение dbt установлено корректно, но функции LSP по-прежнему недоступны, попробуйте следующее:

    1. Проверьте версию расширения — убедитесь, что вы используете последнюю доступную версию расширения dbt, одним из следующих способов:
      • Откройте страницу Extensions в редакторе, или
      • Перейдите на вкладку Output и найдите номер версии, или
      • Выполните dbtf --version в терминале.
    2. Переустановите LSP — если версия актуальна, переустановите LSP:
      1. Откройте палитру команд: Command + Shift + P (macOS) или Ctrl + Shift + P (Windows/Linux).
      2. Вставьте dbt: Reinstall dbt LSP и нажмите Enter.

    Эта команда скачает LSP и повторно активирует расширение, чтобы устранить ошибку.

     Неподдерживаемая версия dbt

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

    Проверьте параметр dbt Path в настройках VS Code. Если этот путь задан, убедитесь, что он указывает на корректный исполняемый файл dbt v2. При необходимости вы также можете установить dbt v2 напрямую, следуя этим инструкциям: Установка CLI dbt v2

     Исполняемый файл dbt v2 не найден по указанному пути

    Если расширение сообщает, что исполняемый файл dbt v2 не найден по указанному пути (например, dbt-fusion binary not found at [path]), параметр dbt.fusionPath указывает на расположение, в котором нет корректного исполняемого файла.

    • Убедитесь, что dbt.fusionPath указывает на корректный исполняемый файл dbt v2.
    • Если вы не устанавливали dbt v2 вручную, очистите значение этого параметра, чтобы расширение само скачало исполняемый файл и управляло им.
    • Для установки вручную следуйте инструкциям в разделе Установка CLI dbt v2.
     Версия dbt v2 несовместима с этим расширением

    Если расширение сообщает, что установленная версия dbt v2 несовместима с вашей версией расширения dbt для VS Code, сочетание этих версий выходит за пределы поддерживаемого диапазона.

    1. Выполните dbt --version, чтобы проверить установленную версию dbt v2.
    2. Сравните ее с матрицей совместимости версий для вашей версии расширения.
    3. Обновите dbt v2 или расширение так, чтобы обе версии входили в поддерживаемый диапазон. Воспользуйтесь действием Download compatible version в уведомлении, если оно отображается.
     dbt v2 аварийно завершается при запуске

    Если расширение сообщает, что dbt v2 аварийно завершился при запуске, убедитесь, что исполняемый файл запускается самостоятельно:

    1. Выполните dbt --version в терминале. Если команда завершается с ошибкой, переустановите dbt v2, следуя инструкциям в разделе Установка CLI dbt v2.
    2. Воспользуйтесь действием Show Logs в уведомлении (или откройте вкладку Output), чтобы изучить ошибку запуска.
     Установлена версия dbt v2 с известными проблемами

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

    Для автономных установок:

    dbt system update

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

     Устранение ошибки 'dbt language server is not running in this workspace'

    Чтобы устранить ошибку dbt language server is not running in this workspace, необходимо добавить папку проекта dbt в рабочую область:

    1. В VS Code нажмите File на панели инструментов, затем выберите Add Folder to Workspace.
    2. Выберите файл проекта dbt, который хотите добавить в рабочую область.
    3. Чтобы сохранить рабочую область, нажмите File, затем выберите Save Workspace As.
    4. Перейдите в расположение, где хотите сохранить рабочую область.

    Это должно устранить ошибку и позволить открыть проект dbt, открыв рабочую область, к которой он относится. Дополнительные сведения о рабочих областях см. в разделе Что такое рабочая область VS Code?.

     Не удается скачать манифест с платформы dbt

    Если расширение dbt для VS Code не может скачать манифест с dbt platform или при локальном использовании dbt v2 вы получаете сообщение warning: dbt1200: Failed to download manifest, вероятно, у вас возникли проблемы с DNS.

    Чтобы проверить это, выполните DNS-запрос для хоста, с которого dbt v2 пытается скачать манифест (например, prodeu2.blob.core.windows.net), с помощью dig в Linux/Mac или nslookup в Windows.

    Если запрос не возвращает IP-адрес, вероятная причина заключается в том, что ваша компания использует того же облачного провайдера с частными конечными точками для облачных ресурсов, а DNS-запросы к ним перенаправляются в частные зоны DNS.

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

    Для Azure см. Резервное разрешение через интернет для частных зон DNS Azure.

    Дополнительная информация о dbt v2​

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

    0