Настройки Profile.yml
profiles.yml. Профиль ClickHouse имеет следующий синтаксис:
Схема и база данных
database.schema.table несовместим с ClickHouse, поскольку ClickHouse не
поддерживает schema.
Поэтому используется упрощённый вариант schema.table, где schema — это база данных ClickHouse. Использовать базу данных default
не рекомендуется.
Предупреждение об операторе SET
Настройка quote_columns
quote_columns в файле dbt_project.yml. Подробнее см. в документации по quote_columns.
О кластере ClickHouse
- Настройку параметра
cluster. - Обеспечение согласованности чтения после записи, особенно если вы используете более одного
threads.
Параметр cluster
cluster в профиле позволяет dbt-clickhouse работать с кластером ClickHouse. Если в профиле задан cluster, по умолчанию все модели будут создаваться с предложением ON CLUSTER — кроме тех, которые используют движок Replicated. Сюда входят:
- Создание базы данных
- Материализации представлений
- Материализации таблиц и incremental-моделей
- Распределённая материализация
ON CLUSTER не добавляется, поскольку они сами управляют репликацией.
Чтобы отключить создание через кластер для конкретной модели, добавьте config disable_on_cluster:
cluster (модель
будет создана только на том узле, к которому установлено подключение).
Совместимость
Если модель была создана без настройки cluster, dbt-clickhouse обнаружит это и выполнит все DDL/DML
без предложения on cluster для этой модели.
Согласованность чтения после записи
- Если вы используете кластер ClickHouse Cloud, достаточно задать
select_sequential_consistency: 1в свойствеcustom_settingsвашего профиля. Подробнее об этой настройке можно узнать здесь. - Если вы используете самоуправляемый кластер, убедитесь, что все запросы dbt отправляются в одну и ту же реплику ClickHouse. Если перед ним установлен балансировщик нагрузки, попробуйте использовать механизм
replica aware routing/sticky sessions, чтобы всегда попадать в одну и ту же реплику. Добавлять настройкуselect_sequential_consistency = 1в кластерах вне ClickHouse Cloud не рекомендуется.
Дополнительные макросы ClickHouse
Вспомогательные макросы материализации моделей
engine_clause— Использует свойство конфигурации modelengineдля назначения движка таблицы ClickHouse. dbt-clickhouse по умолчанию использует движокMergeTree.partition_cols— Использует свойство конфигурации modelpartition_byдля назначения ключа партиционирования ClickHouse. По умолчанию ключ партиционирования не назначается.order_cols— Использует конфигурацию modelorder_byдля назначения ключа сортировки ClickHouse (ORDER BY). Если не указано, ClickHouse будет использовать пустойtuple(), и таблица не будет отсортированаprimary_key_clause— Использует свойство конфигурации modelprimary_keyдля назначения первичного ключа ClickHouse. По умолчанию первичный ключ задан, и ClickHouse будет использовать предложение ORDER BY в качестве первичного ключа.on_cluster_clause— Использует свойство профиляclusterдля добавления предложенияON CLUSTERк некоторым операциям dbt: распределённым материализациям, созданию представлений, созданию баз данных.ttl_config— Использует свойство конфигурации modelttlдля назначения выражения TTL таблицы ClickHouse. По умолчанию TTL не назначается.
Вспомогательный макрос s3Source
s3source упрощает выборку данных ClickHouse напрямую из S3 с помощью табличной функции S3 в ClickHouse. Он работает,
подставляя параметры табличной функции S3 из именованного словаря конфигурации (имя словаря должно оканчиваться
на s3). Макрос
сначала ищет словарь в vars профиля, а затем в конфигурации модели. Словарь может содержать
любые из следующих
ключей, используемых для заполнения параметров табличной функции S3:
См.
тестовый файл S3
с примерами использования этого макроса.
Поддержка макросов для разных баз данных
dbt Core, за следующими исключениями:
- SQL-функция
split_partреализована в ClickHouse с помощью функции splitByChar. Эта функция требует использования константной строки в качестве разделителя дляsplit, поэтому параметрdelimeter, используемый в этом макросе, будет интерпретироваться как строка, а не как имя столбца - Аналогично, SQL-функция
replaceв ClickHouse требует константных строк для параметровold_charsиnew_chars, поэтому при вызове этого макроса эти параметры будут интерпретироваться как строки, а не как имена столбцов.
Поддержка каталога
Статус интеграции с каталогом в dbt
Поддержка каталогов в ClickHouse
experimental, но ими уже можно пользоваться, если у вас установлена актуальная версия ClickHouse.
- Вы можете использовать ClickHouse, чтобы выполнять запросы к таблицам Iceberg, хранящимся в объектном хранилище (S3, Azure Blob Storage, Google Cloud Storage), с помощью движка таблицы Iceberg и табличной функции iceberg.
- Кроме того, ClickHouse предоставляет движок базы данных DataLakeCatalog, который позволяет подключаться к внешним каталогам данных, включая Каталог AWS Glue, Databricks Unity Catalog, Hive Metastore и REST-каталоги. Это позволяет напрямую выполнять запросы к данным в открытых табличных форматах (Iceberg, Delta Lake) из внешних каталогов без дублирования данных.
Обходные решения для работы с Iceberg и каталогами
source. Например, если вы хотите получить доступ к своим таблицам в REST Catalog, вы можете:
- Создать базу данных, указывающую на внешний каталог:
- Определите базу данных каталога и её таблицы как источники в dbt: убедитесь, что эти таблицы уже доступны в ClickHouse
- Используйте таблицы каталога в моделях dbt:
Примечания по обходным решениям
- Вы получите немедленный доступ к различным типам внешних таблиц и внешним каталогам без необходимости ждать появления встроенной интеграции каталогов в dbt.
- У вас будет плавный путь миграции, когда станет доступна встроенная поддержка каталогов.
- Ручная настройка: таблицы Iceberg и базы данных каталогов необходимо создавать вручную в ClickHouse, прежде чем на них можно будет ссылаться в dbt.
- Нет DDL на уровне каталога: dbt не может управлять операциями на уровне каталога, такими как создание или удаление таблиц Iceberg во внешних каталогах. Поэтому сейчас вы не сможете создавать их из коннектора dbt. Возможность создания таблиц с движками Iceberg() может появиться в будущем.
- Операции записи: В настоящее время возможности записи в таблицы Iceberg/Data Catalog ограничены. Ознакомьтесь с документацией ClickHouse, чтобы понять, какие варианты доступны.