(Версии dbt: v2.0 и новее) # Подключение ClickHouse к dbt v2 [Бета-версия](https://docs.getdbt.tech/docs/dbt-versions/product-lifecycles "Подробнее о статусе или тарифе") Локальная разработка Адаптер ClickHouse для dbt v2 подключается к [ClickHouse](https://clickhouse.com) по HTTP или HTTPS. Он поддерживает самостоятельно управляемые одноузловые установки ClickHouse и [ClickHouse Cloud](https://clickhouse.com/cloud). ## Установка dbt Адаптер ClickHouse встроен в v2. Чтобы начать работу, [установите dbt](https://docs.getdbt.tech/docs/local/install-dbt.md). Примеры подключения и настройки профиля приведены в разделе [Подключение к ClickHouse](#connecting-to-clickhouse). ## Аутентификация dbt v2 использует имя пользователя и пароль для аутентификации в ClickHouse. Установите `secure: true` в профиле для подключения по HTTPS (порт по умолчанию — 8443) или не задавайте этот параметр для подключения по обычному HTTP (порт по умолчанию — 8123). Для ClickHouse Cloud требуется `secure: true`. ## Права доступа к хранилищу Пользователь ClickHouse, от имени которого подключается dbt v2, должен иметь возможность выполнять рабочие нагрузки dbt в целевой базе данных и читать системные таблицы, используемые для интроспекции. ### Необходимые объекты ClickHouse Перед подключением следующие объекты должны существовать или быть доступны: | Объект | Назначение | | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Сервис (ClickHouse Cloud) или сервер (самостоятельно управляемый, с одним узлом) | Вычислительный ресурс | | База данных | Целевая база данных. В ClickHouse нет отдельного уровня схем, поэтому `schema` в dbt соответствует базе данных | | Пользователь | Пользователь базы данных для аутентификации | ### Основные права доступа Для основных возможностей dbt требуются следующие права доступа: | Право доступа | Объект | Назначение | | -------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SELECT` | Таблицы и представления | Чтение данных | | `INSERT` | Таблицы | Загрузка моделей, seed-файлов и снимков | | `ALTER` | Таблицы | Изменение схемы (`on_schema_change`), индексы и проекции, комментарии (`persist_docs`), `REPLACE PARTITION` (`insert_overwrite`) и легковесные удаления (`delete+insert`) | | `TRUNCATE` | Таблицы | Полное обновление данных из seed-файлов | | `CREATE TABLE`, `CREATE VIEW`, `CREATE DICTIONARY` | База данных | Создание материализаций, включая промежуточные и резервные объекты, используемые для атомарного пересоздания (`EXCHANGE TABLES`, `RENAME TABLE`) | | `DROP TABLE`, `DROP VIEW`, `DROP DICTIONARY` | База данных | Удаление или замена объектов | ### Операции с метаданными dbt v2 читает следующие системные таблицы ClickHouse: | Системная таблица | Назначение | | ----------------------- | ------------------------------------------------------------------------------------------------------------------- | | `system.tables` | Получение списка объектов, построение каталога, обнаружение материализованных представлений, ссылающихся на таблицу | | `system.columns` | Метаданные столбцов для каталога и обнаружения изменений схемы | | `system.databases` | Проверка существования целевой базы данных | | `system.settings` | Проверка доступности возможностей (легковесные удаления, `insert_distributed_sync`) | | `system.view_refreshes` | Проверка зависимостей обновляемых материализованных представлений | ClickHouse фильтрует системные таблицы, оставляя только объекты, к которым у пользователя есть доступ, поэтому отдельно предоставлять права на эти таблицы не требуется. ### Управление базами данных Права доступа для управления базами данных, необходимые при определённых условиях: | Право доступа | Объект | Когда требуется | | ----------------- | ------ | ----------------------------------------------------------------------- | | `CREATE DATABASE` | Сервер | Автоматическое создание целевой базы данных, если она ещё не существует | ## Ограничения Адаптер ClickHouse для dbt v2 находится на стадии бета-тестирования. Возможны небольшие ошибки, поэтому пока не используйте его в производственных средах. Некоторые возможности адаптера `dbt-clickhouse` для dbt v1 пока не поддерживаются. Адаптер ClickHouse активно разрабатывается. Если вы столкнулись с проблемой, [создайте issue в dbt-core](https://github.com/dbt-labs/dbt-core/issues/new) и добавьте метку `adapter:clickhouse`. ### Что уже работает В одноузловых установках ClickHouse и в ClickHouse Cloud (с поддержкой многоузловых кластеров): * Все материализации: table, view, incremental (все стратегии и `on_schema_change`), materialized view (включая обновляемые), dictionary, snapshot, seed и ephemeral * Контракты и ограничения, `settings` для моделей и запросов, проекции и индексы * Тесты данных, модульные тесты, генерация каталога и табличная функция `s3` ### Что пока не поддерживается * Самостоятельно управляемые кластеры с параметром `cluster:` в профиле пока не поддерживаются. В инструкции языка определения данных (DDL) не добавляется `ON CLUSTER`, поэтому движки Replicated и материализации `distributed_table` и `distributed_incremental` не работают. * Конфигурация `grants`, а также команды `dbt clone` и `dbt source freshness` пока не поддерживаются. * Сохраняются и менее значительные ограничения: `query-comment: null` не учитывается, результаты выполнения не включают ClickHouse `query_id`, а описания `persist_docs`, содержащие `;`, приводят к ошибке. * Функции анализа SQL (статический анализ и остальные интеллектуальные возможности dbt для работы с SQL) пока недоступны. Поддержка появится в ближайшее время. * В основных функциях работы с ClickHouse всё ещё могут встречаться небольшие ошибки. ## Подключение к ClickHouse Чтобы подключиться к ClickHouse из dbt, необходимо добавить [профиль](https://docs.getdbt.tech/docs/local/profiles.yml.md) в файл конфигурации `profiles.yml`. Используйте приведённый ниже пример конфигурации для настройки профиля ClickHouse: profiles.yml ```yaml clickhouse-service: target: dev outputs: dev: type: clickhouse schema: [ default ] # База данных ClickHouse для моделей dbt # необязательные параметры host: [ ] # URL вашего кластера ClickHouse, например abc123.clickhouse.cloud. По умолчанию — `localhost`. port: [ 8123 ] # По умолчанию — 8123, 8443, 9000 или 9440 в зависимости от настроек secure и driver user: [ default ] # Пользователь для всех операций с базой данных password: [ ] # Пароль пользователя secure: [ False ] # Использовать TLS (протокол native) или HTTPS (протокол http). Для ClickHouse Cloud необходимо установить true. ``` Полный список параметров конфигурации приведён в [документации ClickHouse](https://clickhouse.com/docs/integrations/dbt). ### Создание проекта dbt Теперь вы можете использовать этот профиль в одном из существующих проектов или создать новый с помощью команды: ```sh dbt init project_name ``` Перейдите в каталог `project_name` и обновите файл `dbt_project.yml`, чтобы использовать профиль, настроенный для подключения к ClickHouse. ```yaml profile: 'clickhouse-service' ``` ### Проверка подключения Выполните `dbt debug` в командной строке, чтобы проверить, может ли dbt подключиться к ClickHouse. Убедитесь, что ответ содержит `Connection test: [OK connection ok]`, что указывает на успешное подключение.