Возможности и конфигурации

В этом разделе описаны некоторые возможности dbt для ClickHouse.

Чтобы подключить dbt к ClickHouse, нужно добавить профиль в файл profiles.yml. Профиль ClickHouse имеет следующий синтаксис:

your_profile_name:
  target: dev
  outputs:
    dev:
      type: clickhouse

      # Optional
      schema: [default] # ClickHouse database for dbt models
      driver: [http] # http or native.  If not set this will be autodetermined based on port setting
      host: [localhost] 
      port: [8123]  # If not set, defaults to 8123, 8443, 9000, 9440 depending on the secure and driver settings 
      user: [default] # User for all database operations
      password: [<empty string>] # Password for the user
      cluster: [<empty string>] # If set, certain DDL/table operations will be executed with the `ON CLUSTER` clause using this cluster. Distributed materializations require this setting to work. See the following ClickHouse Cluster section for more details.
      verify: [True] # Validate TLS certificate if using TLS/SSL
      secure: [False] # Use TLS (native protocol) or HTTPS (http protocol)
      client_cert: [null] # Path to a TLS client certificate in .pem format
      client_cert_key: [null] # Path to the private key for the TLS client certificate
      server_host_name: [null] # Override the TLS SNI and hostname verification target. Useful when connecting via a DNS alias (e.g. an internal CNAME or AWS PrivateLink endpoint) where the TLS certificate is issued for a different hostname than the one used in `host`.
      retries: [1] # Number of times to retry a "retriable" database exception (such as a 503 'Service Unavailable' error)
      compression: [<empty string>] # Use gzip compression if truthy (http), or compression type for a native connection
      connect_timeout: [10] # Timeout in seconds to establish a connection to ClickHouse
      send_receive_timeout: [300] # Timeout in seconds to receive data from the ClickHouse server
      cluster_mode: [False] # Use specific settings designed to improve operation on Replicated databases (recommended for ClickHouse Cloud)
      use_lw_deletes: [False] # Use the strategy `delete+insert` as the default incremental strategy.
      check_exchange: [True] # Validate that clickhouse support the atomic EXCHANGE TABLES command.  (Not needed for most ClickHouse versions)
      local_suffix: [_local] # Table suffix of local tables on shards for distributed materializations.
      local_db_prefix: [<empty string>] # Database prefix of local tables on shards for distributed materializations. If empty, it uses the same database as the distributed table.
      allow_automatic_deduplication: [False] # Enable ClickHouse automatic deduplication for Replicated tables
      tcp_keepalive: [False] # Native client only, specify TCP keepalive configuration. Specify custom keepalive settings as [idle_time_sec, interval_sec, probes].
      reuse_connections: [True] # Re-use the same connection across models. Set to `False` to close the connection at the end of each model — useful on multi-replica ClickHouse Cloud services where the load balancer routes by TCP connection. Note: disabling connection reuse adds a new TCP/TLS handshake per model, which increases total `dbt run` wall time (typically ~200-500 ms per model). Combine with `threads > 1` for the best balance between distribution and throughput.
      custom_settings: [{}] # A dictionary/mapping of custom ClickHouse settings for the connection - default is empty.
      database_engine: '' # Database engine to use when creating new ClickHouse schemas (databases).  If not set (the default), new databases will use the default ClickHouse database engine (usually Atomic).
      threads: [1] # Number of threads to use when running queries. Before setting it to a number higher than 1, make sure to read the [read-after-write consistency](#read-after-write-consistency) section.
      
      # Native (clickhouse-driver) connection settings
      sync_request_timeout: [5] # Timeout for server ping
      compress_block_size: [1048576] # Compression block size if compression is enabled

Идентификатор отношения модели dbt database.schema.table несовместим с ClickHouse, поскольку ClickHouse не поддерживает schema. Поэтому используется упрощённый вариант schema.table, где schema — это база данных ClickHouse. Использовать базу данных default не рекомендуется.

Во многих средах использование оператора SET для сохранения настройки ClickHouse во всех запросах DBT ненадежно и может приводить к неожиданным сбоям. Это особенно актуально при использовании HTTP-соединений через балансировщик нагрузки, который распределяет запросы между несколькими узлами (например, в ClickHouse Cloud), хотя в некоторых случаях это также может происходить и при использовании нативных соединений ClickHouse. Поэтому в качестве рекомендуемой практики мы советуем задавать все необходимые настройки ClickHouse в свойстве "custom_settings" профиля DBT, а не полагаться на pre-hook-оператор "SET", как иногда рекомендуется.

Чтобы избежать предупреждения, явно задайте значение quote_columns в файле dbt_project.yml. Подробнее см. в документации по quote_columns.

seeds:
  +quote_columns: false  #или `true`, если заголовки столбцов CSV содержат пробелы

При использовании кластера ClickHouse нужно учитывать две вещи:

• Настройку параметра cluster.
• Обеспечение согласованности чтения после записи, особенно если вы используете более одного threads.

Параметр cluster в профиле позволяет dbt-clickhouse работать с кластером ClickHouse. Если в профиле задан cluster, по умолчанию все модели будут создаваться с предложением ON CLUSTER — кроме тех, которые используют движок Replicated. Сюда входят:

• Создание базы данных
• Материализации представлений
• Материализации таблиц и incremental-моделей
• Распределённая материализация

Для движков Replicated предложение ON CLUSTER не добавляется, поскольку они сами управляют репликацией.

Чтобы отключить создание через кластер для конкретной модели, добавьте config disable_on_cluster:

{{ config(
        engine='MergeTree',
        materialized='table',
        disable_on_cluster='true'
    )
}}

Материализации table и incremental с нереплицируемым движком не будут зависеть от настройки cluster (модель будет создана только на том узле, к которому установлено подключение).

Совместимость

Если модель была создана без настройки cluster, dbt-clickhouse обнаружит это и выполнит все DDL/DML без предложения on cluster для этой модели.

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

• Если вы используете кластер ClickHouse Cloud, достаточно задать select_sequential_consistency: 1 в свойстве custom_settings вашего профиля. Подробнее об этой настройке можно узнать здесь.
• Если вы используете самоуправляемый кластер, убедитесь, что все запросы dbt отправляются в одну и ту же реплику ClickHouse. Если перед ним установлен балансировщик нагрузки, попробуйте использовать механизм replica aware routing/sticky sessions, чтобы всегда попадать в одну и ту же реплику. Добавлять настройку select_sequential_consistency = 1 в кластерах вне ClickHouse Cloud не рекомендуется.

Следующие макросы включены для упрощения создания таблиц и представлений ClickHouse:

• engine_clause – Использует свойство конфигурации model engine для назначения движка таблицы ClickHouse. dbt-clickhouse по умолчанию использует движок MergeTree.
• partition_cols – Использует свойство конфигурации model partition_by для назначения ключа партиционирования ClickHouse. По умолчанию ключ партиционирования не назначается.
• order_cols – Использует конфигурацию model order_by для назначения ключа сортировки ClickHouse (ORDER BY). Если не указано, ClickHouse будет использовать пустой tuple(), и таблица не будет отсортирована
• primary_key_clause – Использует свойство конфигурации model primary_key для назначения первичного ключа ClickHouse. По умолчанию первичный ключ задан, и ClickHouse будет использовать предложение ORDER BY в качестве первичного ключа.
• on_cluster_clause – Использует свойство профиля cluster для добавления предложения ON CLUSTER к некоторым операциям dbt: распределённым материализациям, созданию представлений, созданию баз данных.
• ttl_config – Использует свойство конфигурации model ttl для назначения выражения TTL таблицы ClickHouse. По умолчанию TTL не назначается.

Макрос s3source упрощает выборку данных ClickHouse напрямую из S3 с помощью табличной функции S3 в ClickHouse. Он работает, подставляя параметры табличной функции S3 из именованного словаря конфигурации (имя словаря должно оканчиваться на s3). Макрос сначала ищет словарь в vars профиля, а затем в конфигурации модели. Словарь может содержать любые из следующих ключей, используемых для заполнения параметров табличной функции S3:

Определите общую конфигурацию в dbt_project.yml (имя словаря должно оканчиваться на s3):

vars:
  taxi_s3:
    bucket: 'datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi'
    fmt: 'TabSeparatedWithNames'

Затем вызовите макрос в модели. Любой из указанных выше аргументов можно также передать непосредственно при вызове — они будут иметь приоритет над значениями словаря:

select * from {{ clickhouse_s3source('taxi_s3', path='/trips_4.gz') }}

См. тестовый файл S3 для дополнительных примеров.

dbt-clickhouse теперь поддерживает большинство макросов для разных баз данных, включённых в dbt Core, за следующими исключениями:

• SQL-функция split_part реализована в ClickHouse с помощью функции splitByChar. Эта функция требует использования константной строки в качестве разделителя для split, поэтому параметр delimeter, используемый в этом макросе, будет интерпретироваться как строка, а не как имя столбца
• Аналогично, SQL-функция replace в ClickHouse требует константных строк для параметров old_chars и new_chars, поэтому при вызове этого макроса эти параметры будут интерпретироваться как строки, а не как имена столбцов.

В dbt Core v1.10 появилась поддержка интеграции с каталогами, которая позволяет адаптерам материализовывать модели во внешние каталоги, управляющие открытыми табличными форматами, такими как Apache Iceberg. Эта возможность пока ещё не реализована в dbt-clickhouse на нативном уровне. Отслеживать ход реализации этой возможности можно в issue #489 на GitHub.

Недавно ClickHouse добавил встроенную поддержку таблиц Apache Iceberg и каталогов данных. Большинство возможностей всё ещё имеют статус 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 или каталогов в своем проекте dbt, если уже настроили их в кластере ClickHouse с помощью описанных выше инструментов. Для обращения к этим таблицам в проектах dbt можно использовать функциональность source. Например, если вы хотите получить доступ к своим таблицам в REST Catalog, вы можете:

1. Создать базу данных, указывающую на внешний каталог:

-- Пример с REST-каталогом
SET allow_experimental_database_iceberg = 1;

CREATE DATABASE iceberg_catalog
ENGINE = DataLakeCatalog('http://rest:8181/v1', 'admin', 'password')
SETTINGS 
    catalog_type = 'rest', 
    storage_endpoint = 'http://minio:9000/lakehouse', 
    warehouse = 'demo'

2. Определите базу данных каталога и её таблицы как источники в dbt: убедитесь, что эти таблицы уже доступны в ClickHouse

version: 2

sources:
  - name: external_catalog
    database: iceberg_catalog
    tables:
      - name: orders
      - name: customers

3. Используйте таблицы каталога в моделях dbt:

SELECT 
    o.order_id,
    c.customer_name,
    o.order_date
FROM {{ source('external_catalog', 'orders') }} o
INNER JOIN {{ source('external_catalog', 'customers') }} c
    ON o.customer_id = c.customer_id

Преимущества этих обходных решений:

• Вы получите немедленный доступ к различным типам внешних таблиц и внешним каталогам без необходимости ждать появления встроенной интеграции каталогов в dbt.
• У вас будет плавный путь миграции, когда станет доступна встроенная поддержка каталогов.

Но сейчас есть и некоторые ограничения:

• Ручная настройка: таблицы Iceberg и базы данных каталогов необходимо создавать вручную в ClickHouse, прежде чем на них можно будет ссылаться в dbt.
• Нет DDL на уровне каталога: dbt не может управлять операциями на уровне каталога, такими как создание или удаление таблиц Iceberg во внешних каталогах. Поэтому сейчас вы не сможете создавать их из коннектора dbt. Возможность создания таблиц с движками Iceberg() может появиться в будущем.
• Операции записи: В настоящее время возможности записи в таблицы Iceberg/Data Catalog ограничены. Ознакомьтесь с документацией ClickHouse, чтобы понять, какие варианты доступны.