(Версии dbt: v2.0 и новее)

Подключение ClickHouse к dbt v2 Бета-версия

Адаптер ClickHouse для dbt v2 подключается к ClickHouse по HTTP или HTTPS. Он поддерживает самостоятельно управляемые одноузловые установки ClickHouse и ClickHouse Cloud.

Установка dbt

Адаптер ClickHouse встроен в v2. Чтобы начать работу, установите dbt.

Примеры подключения и настройки профиля приведены в разделе Подключение к 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 и добавьте метку 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, необходимо добавить профиль в файл конфигурации profiles.yml. Используйте приведённый ниже пример конфигурации для настройки профиля ClickHouse:

profiles.yml

clickhouse-service:
  target: dev
  outputs:
    dev:
      type: clickhouse
      schema: [ default ]  # База данных ClickHouse для моделей dbt

      # необязательные параметры
      host: [ <your-clickhouse-host> ]  # URL вашего кластера ClickHouse, например abc123.clickhouse.cloud. По умолчанию — `localhost`.
      port: [ 8123 ]  # По умолчанию — 8123, 8443, 9000 или 9440 в зависимости от настроек secure и driver 
      user: [ default ]  # Пользователь для всех операций с базой данных
      password: [ <empty string> ]  # Пароль пользователя
      secure: [ False ]  # Использовать TLS (протокол native) или HTTPS (протокол http). Для ClickHouse Cloud необходимо установить true.

Сообщить об ошибке в коде

Полный список параметров конфигурации приведён в документации ClickHouse.

Создание проекта dbt

Теперь вы можете использовать этот профиль в одном из существующих проектов или создать новый с помощью команды:

dbt init project_name

Сообщить об ошибке в коде

Перейдите в каталог project_name и обновите файл dbt_project.yml, чтобы использовать профиль, настроенный для подключения к ClickHouse.

profile: 'clickhouse-service'

Сообщить об ошибке в коде

Проверка подключения

Выполните dbt debug в командной строке, чтобы проверить, может ли dbt подключиться к ClickHouse. Убедитесь, что ответ содержит Connection test: [OK connection ok], что указывает на успешное подключение.

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

Создать GitHub Issue