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

Быстрый старт с dbt v1 и DuckDB

Быстрый старт
Начальный уровень
Menu

    Введение​

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

    В этом руководстве используется DuckDB с CLI dbt v1. Для dbt v2 см. Настройка DuckDB.

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

    • Создайте виртуальную среду разработки с помощью шаблона, предоставленного dbt Labs.
    • Мы настроим полнофункциональную среду dbt с рабочим проектом, готовым к запуску. Среда codespace автоматически подключается к базе данных DuckDB и загружает данные за год из нашего вымышленного кафе Jaffle Shop, которое продаёт еду и напитки в нескольких городах США.
    • Выполните шаги, описанные в репозитории jaffle_shop_duckdb, а если хотите подробнее изучить код, обратитесь к README шаблона Jaffle Shop.
    • Выполните любую команду dbt в терминале среды.
    • Сгенерируйте более объёмный набор данных для кафе Jaffle Shop (например, данные за пять лет вместо одного года).
    Follow along with an AI assistantCopy and paste this prompt into your AI assistant to guide you through each step

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

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

    • При использовании DuckDB с dbt v1 вам потребуется CLI. В настоящее время DuckDB не поддерживается в dbt platform.
    • Важно знать основы работы с терминалом. В частности, вы должны понимать, как использовать cd, ls и pwd, чтобы легко перемещаться по структуре каталогов вашего компьютера.
    • У вас есть учётная запись GitHub.
    • У вас установлен Python 3.12 или более поздней версии. При использовании более ранних версий установка зависимостей из requirements.txt может завершиться ошибкой (например, для networkx 3.7 требуется Python 3.12 или более поздней версии).

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

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

    В репозитории есть файл requirements.txt, который используется для установки dbt v1, 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.

    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 v1 и 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=x.y.z
    15:10:13 Registered adapter: duckdb=x.y.z
    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 (простое отключение не всегда помогает).

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

    Локальное хранилище​

    DuckDB хранит данные в локальном файле .duckdb. Его расположение задаёт поле path в profiles.yml.

    В этом руководстве проект использует файл jaffle_shop.duckdb. После запуска dbt build проверьте, что файл базы данных создан, следующей командой:

    ls -lah *.duckdb

    В каталоге проекта должен появиться файл jaffle_shop.duckdb. Он содержит таблицы и представления, созданные dbt, и сохраняется между запусками.

    Если удалить файл:

    rm *.duckdb

    Повторный запуск dbt build создаст его заново.

    примечание

    Относительный путь, например ./local.duckdb, отсчитывается от каталога, где находится profiles.yml.

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

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

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

      python -m pip install jafgen
    2. После завершения установки выполните:

    jafgen NUMBER_OF_YEARS

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

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

    ## Следующие шаги \{#next-steps}

    - Страница О проектах знакомит вас со структурой проекта dbt и его компонентами.
    - Справочник команд dbt описывает доступные команды и их назначение.
    - Курсы dbt Labs предлагают разнообразные учебные модули начального, среднего и продвинутого уровней, которые помогут вам стать экспертом по dbt.
    - Когда вы оцените потенциал dbt и поймёте, какую пользу он может принести вашей организации, зарегистрируйтесь для бесплатного пробного использования dbt. Это самый быстрый и простой способ развернуть dbt уже сегодня!
    - Ознакомьтесь с другими руководствами по быстрому старту, чтобы начать интеграцию с вашим существующим хранилищем данных.

    - Страница About projects описывает структуру проекта dbt и его компоненты.
    - В справочнике команд dbt описаны доступные команды и их назначение.
    - Курсы dbt Labs предлагают обучающие модули начального, среднего и продвинутого уровня, которые помогут вам стать экспертом по dbt.
    - Когда вы увидите потенциал dbt для вашей организации, зарегистрируйтесь для бесплатного пробного периода <Constant name="cloud" />. Это самый быстрый и простой способ развернуть dbt на сегодняшний день.
    - Ознакомьтесь с другими quickstart‑руководствами, чтобы начать интеграцию с вашим существующим хранилищем данных.

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

    ### Документирование проекта \{#document-your-project}

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

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

    ### Фиксация изменений \{#commit-your-changes}

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

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

    ```shell
    git add .
    git commit -m "Your commit message"
    git push
    1. Вернитесь в репозиторий GitHub и убедитесь, что новые файлы были добавлены.

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

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

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

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

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

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

    0