Быстрый старт для dbt Core с использованием DuckDB

Назад к гайдам

dbt Core

Quickstart

Beginner

Menu

Введение

В этом кратком руководстве вы узнаете, как использовать dbt Core вместе с DuckDB, чтобы быстро и эффективно начать работу. DuckDB — это система управления базами данных с открытым исходным кодом, предназначенная для аналитических нагрузок. Она обеспечивает быстрый и удобный доступ к большим наборам данных, что делает её хорошо подходящей для задач аналитики данных.

В этом руководстве будет показано, как:

• Создать виртуальное окружение для разработки с использованием шаблона, предоставленного dbt Labs.
• Настроить полностью рабочее окружение dbt с готовым к выполнению проектом. Codespace автоматически подключается к базе данных DuckDB и загружает данные за один год из нашего вымышленного кафе Jaffle Shop, которое продаёт еду и напитки в нескольких городах США.
• Пройти шаги, описанные в репозитории jaffle_shop_duck_db, а если вы хотите глубже разобраться в исходном коде, обратиться к README шаблона Jaffle Shop.
• Выполнять любые команды dbt из терминала окружения.
• Сгенерировать больший набор данных для кафе Jaffle Shop (например, данные за пять лет вместо одного).

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

Связанный контент

• Настройка DuckDB
• Создание репозитория GitHub
• Создание первых моделей
• Тестирование и документирование проекта

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

• При использовании DuckDB с dbt Core необходимо работать через интерфейс командной строки dbt (CLI). В настоящее время DuckDB не поддерживается в dbt.
• Важно иметь базовые навыки работы с терминалом. В частности, вы должны понимать команды cd, ls и pwd, чтобы уверенно перемещаться по структуре каталогов на вашем компьютере.
• У вас есть аккаунт GitHub.

Настройка DuckDB для dbt Core

В этом разделе приведено пошаговое руководство по настройке DuckDB для использования в локальных окружениях (Mac и Windows) и в веб-браузере.

В репозитории есть файл requirements.txt, который используется для установки dbt Core, DuckDB и всех необходимых зависимостей. Вы можете ознакомиться с этим файлом, чтобы понять, что именно будет установлено на вашем компьютере. Обычно он находится в корневом каталоге проекта рядом с такими ключевыми файлами, как dbt_project.yml. В противном случае мы покажем это на следующих шагах.

Ниже приведён пример файла requirements.txt рядом с другими ключевыми файлами, такими как dbt_project.yml:

/my_dbt_project/
├── dbt_project.yml
├── models/
│   ├── my_model.sql
├── tests/
│   ├── my_test.sql
└── requirements.txt

Для получения дополнительной информации см. настройку DuckDB.

Local

1. Сначала клонируйте git-репозиторий Jaffle Shop, выполнив следующую команду в терминале:

   git clone https://github.com/dbt-labs/jaffle_shop_duckdb.git
   

2. Перейдите в каталог jaffle_shop_duckdb из командной строки:

   
   cd jaffle_shop_duckdb
   

3. Установите dbt Core и DuckDB в виртуальное окружение.

    Пример для Mac

   
   python3 -m venv venv
   source venv/bin/activate
   python3 -m pip install --upgrade pip
   python3 -m pip install -r requirements.txt
   source venv/bin/activate
   
    Пример для Windows

   
   python -m venv venv
   venv\Scripts\activate.bat
   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt
   venv\Scripts\activate.bat
   
    Пример для Windows PowerShell

   
   python -m venv venv
   venv\Scripts\Activate.ps1
   python -m pip install --upgrade pip
   python -m pip install -r requirements.txt
   venv\Scripts\Activate.ps1
   

4. Убедитесь, что ваш профиль настроен корректно, выполнив следующие команды dbt из командной строки:

   • dbt seed — загружает CSV-файлы из каталога seed-paths проекта в хранилище данных
   • dbt compile — генерирует исполняемый SQL из исходных файлов проекта
   • dbt run — компилирует и выполняет проект
   • dbt test — компилирует и запускает тесты проекта
   • dbt build — компилирует, выполняет и тестирует проект
   • dbt docs generate — генерирует документацию проекта
   • dbt docs serve — запускает веб-сервер на порту 8080 для локального просмотра документации и автоматически открывает сайт в браузере по умолчанию

Полные сведения см. в справочнике команд dbt.

Ниже показан пример успешного вывода:

(venv) ➜  jaffle_shop_duckdb git:(duckdb) dbt build
15:10:12  Running with dbt=1.8.1
15:10:13  Registered adapter: duckdb=1.8.1
15:10:13  Found 5 models, 3 seeds, 20 data tests, 416 macros
15:10:13  
15:10:14  Concurrency: 24 threads (target='dev')
15:10:14  
15:10:14  1 of 28 START seed file main.raw_customers ..................................... [RUN]
15:10:14  2 of 28 START seed file main.raw_orders ........................................ [RUN]
15:10:14  3 of 28 START seed file main.raw_payments ...................................... [RUN]
....

15:10:15  27 of 28 PASS relationships_orders_customer_id__customer_id__ref_customers_ .... [PASS in 0.32s]
15:10:15  
15:10:15  Finished running 3 seeds, 3 view models, 20 data tests, 2 table models in 0 hours 0 minutes and 1.52 seconds (1.52s).
15:10:15  
15:10:15  Completed successfully
15:10:15  
15:10:15  Done. PASS=28 WARN=0 ERROR=0 SKIP=0 TOTAL=28

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

• dbt show --select "raw_orders" — выполняет запрос к хранилищу данных и показывает предварительный просмотр результатов в терминале.
• dbt source — предоставляет подкоманды, такие как dbt source freshness, полезные при работе с исходными данными.
  • dbt source freshness — проверяет свежесть (насколько актуальны данные) конкретной таблицы-источника.

примечание

Эти шаги завершатся ошибкой, если вы попытаетесь запустить данный проект в другом хранилище данных (за пределами этого демонстрационного примера с DuckDB). В этом случае потребуется перенастроить файлы проекта под ваше хранилище. Обязательно учитывайте это, если вы используете адаптер, поддерживаемый сообществом.

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

 Ошибка Could not set lock on file

IO Error: Could not set lock on file "jaffle_shop.duckdb": Resource temporarily unavailable

Это известная проблема DuckDB. Попробуйте отключиться от всех сессий, которые блокируют базу данных. Если вы используете DBeaver, это означает полное закрытие DBeaver (простое отключение не всегда помогает).

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

Веб-браузер

1. Перейдите в репозиторий jaffle-shop-template на GitHub после входа в свой аккаунт.

2. Нажмите Use this template в верхней части страницы и выберите Create new repository.

3. После настройки параметров нового репозитория нажмите Create repository from template.

4. Нажмите Code (в верхней части страницы нового репозитория). На вкладке Codespaces выберите Create codespace on main. В зависимости от настроек вашего компьютера откроется новая вкладка браузера с окружением Codespace и запущенным VSCode либо новое окно VSCode с этим codespace.

5. Дождитесь завершения сборки codespace — необходимо, чтобы команда postCreateCommand завершилась; это может занять несколько минут:

   Дождитесь завершения postCreateCommand

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

6. В терминале вы можете выполнять любые команды dbt. Например:

   /workspaces/test (main) $ dbt build

   Вы также можете использовать duckcli для написания SQL-запросов к хранилищу из командной строки или для построения отчётов в проекте Evidence, который находится в каталоге reports.

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

   • dbt compile — генерирует исполняемый SQL из исходных файлов проекта
   • dbt run — компилирует и выполняет проект
   • dbt test — компилирует и запускает тесты проекта
   • dbt build — компилирует, выполняет и тестирует проект

Генерация большего набора данных

Если вы хотите работать с большим объёмом данных Jaffle Shop, вы можете сгенерировать произвольное количество лет фиктивных данных прямо в вашем codespace.

1. Установите Python-пакет jafgen. В терминале выполните:

   python -m pip install jafgen

2. После завершения установки выполните:

   jafgen [number of years to generate] # e.g. jafgen 6

   Замените NUMBER_OF_YEARS на количество лет, которое вы хотите смоделировать. Например, чтобы сгенерировать данные за 6 лет, выполните: jafgen --years 6. Эта команда создаёт CSV-файлы и сохраняет их в папке jaffle-data. Данные автоматически подключаются на основе файла sources.yml и адаптера dbt-duckdb.

По мере увеличения количества лет время генерации данных растёт экспоненциально, так как магазины Jaffle Shop увеличиваются в размере и количестве. Для разумного баланса между объёмом данных и временем сборки dbt Labs рекомендует максимум 6 лет.

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

Теперь, когда dbt Core, DuckDB и данные Jaffle Shop успешно настроены и работают, вы можете начать изучать возможности dbt. Для более глубокого понимания проектов и команд dbt ознакомьтесь со следующими материалами:

• Страница About projects описывает структуру проекта dbt и его компоненты.
• dbt command reference объясняет доступные команды и их назначение.
• Курсы dbt Labs предлагают обучающие модули начального, среднего и продвинутого уровня, которые помогут вам стать экспертом по dbt.
• Когда вы увидите потенциал dbt для вашей организации, зарегистрируйтесь для бесплатного пробного периода dbt. Это самый быстрый и простой способ развернуть dbt на сегодняшний день.
• Ознакомьтесь с другими quickstart‑руководствами, чтобы начать интеграцию с вашим существующим хранилищем данных.

Кроме того, с новым пониманием основ работы с DuckDB стоит рассмотреть оптимизацию вашей настройки: документируйте проект, зафиксируйте изменения и настройте расписание выполнения.

Документирование проекта

Чтобы задокументировать проекты dbt с DuckDB, выполните следующие шаги:

• Используйте команду dbt docs generate для компиляции информации о проекте dbt и хранилище данных в файлы manifest.json и catalog.json
• Запустите команду dbt docs serve, чтобы создать локальный веб‑сайт на основе сгенерированных .json‑файлов. Это позволит просматривать документацию проекта в браузере.
• Улучшите документацию, добавляя описания моделей, колонок и источников с помощью ключа description в YAML‑файлах.

Фиксация изменений

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

1. В созданном вами GitHub‑репозитории выполните в терминале следующие команды:

git add 
git commit -m "Your commit message"
git push

2. Вернитесь в репозиторий GitHub и убедитесь, что новые файлы были добавлены.

Планирование задания

1. Убедитесь, что dbt Core установлен и настроен для подключения к вашему экземпляру DuckDB.
2. Создайте проект dbt и определите ваши models, seeds и tests.
3. Используйте планировщик, например Prefect, чтобы запускать задания dbt по расписанию. Вы можете создать DAG (направленный ациклический граф), который будет запускать команды dbt через заданные интервалы.
4. Напишите скрипт, который выполняет команды dbt, такие как dbt run, dbt test и другие.
5. Используйте выбранный планировщик для запуска скрипта с нужной периодичностью.

Поздравляем с успешным прохождением руководства 🎉!

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

Создать GitHub Issue