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

Подключение dlt к ClickHouse

Partner Integration

dlt — это библиотека с открытым исходным кодом, которую можно добавить в Python-скрипты, чтобы загружать данные из различных, часто «грязных» источников в хорошо структурированные, постоянно обновляемые наборы данных.

Установка dlt с ClickHouse​

Установите библиотеку dlt с зависимостями для ClickHouse:​

pip install "dlt[clickhouse]"

Руководство по настройке​

Инициализация проекта dlt​

Начните с инициализации нового проекта dlt следующим образом:

dlt init chess clickhouse
Примечание

Эта команда инициализирует ваш конвейер с chess в качестве источника и ClickHouse в качестве назначения.

Приведённая выше команда создаёт несколько файлов и каталогов, включая .dlt/secrets.toml и файл требований для ClickHouse. Вы можете установить необходимые зависимости, указанные в файле требований, выполнив следующую команду:

pip install -r requirements.txt

или с помощью pip install dlt[clickhouse], что устанавливает библиотеку dlt и необходимые зависимости для работы с ClickHouse в качестве назначения.

Настройка базы данных ClickHouse​

Для загрузки данных в ClickHouse необходимо создать базу данных ClickHouse. Ниже приведён общий план действий:

  1. Вы можете использовать существующую базу данных ClickHouse или создать новую.

  2. Для создания новой базы данных подключитесь к серверу ClickHouse с помощью инструмента командной строки clickhouse-client или SQL-клиента по вашему выбору.

  3. Выполните следующие SQL-команды для создания новой базы данных, пользователя и предоставления необходимых разрешений:

CREATE DATABASE IF NOT EXISTS dlt;
CREATE USER dlt IDENTIFIED WITH sha256_password BY 'Dlt*12345789234567';
GRANT CREATE, ALTER, SELECT, DELETE, DROP, TRUNCATE, OPTIMIZE, SHOW, INSERT, dictGet ON dlt.* TO dlt;
GRANT SELECT ON INFORMATION_SCHEMA.COLUMNS TO dlt;
GRANT CREATE TEMPORARY TABLE, S3 ON *.* TO dlt;

Добавление учётных данных​

Далее настройте учётные данные ClickHouse в файле .dlt/secrets.toml, как показано ниже:

[destination.clickhouse.credentials]
database = "dlt"                         # Имя созданной базы данных
username = "dlt"                         # Имя пользователя ClickHouse, по умолчанию обычно "default"
password = "Dlt*12345789234567"          # Пароль ClickHouse, если установлен
host = "localhost"                       # Хост сервера ClickHouse
port = 9000                              # Порт ClickHouse, по умолчанию 9000
http_port = 8443                         # Порт HTTP для подключения к HTTP-интерфейсу сервера ClickHouse. По умолчанию 8443.
secure = 1                               # Установите 1 при использовании HTTPS, иначе 0.

[destination.clickhouse]
dataset_table_separator = "___"          # Разделитель для имён таблиц набора данных.
HTTP_PORT

Параметр http_port указывает номер порта, используемый при подключении к HTTP-интерфейсу сервера ClickHouse. Это отличается от порта по умолчанию 9000, который используется для нативного протокола TCP.

Вы должны установить http_port, если не используете внешнее промежуточное хранилище (т. е. не устанавливаете параметр staging в вашем конвейере). Это связано с тем, что встроенное промежуточное хранилище ClickHouse использует библиотеку clickhouse-connect, которая взаимодействует с ClickHouse по HTTP.

Убедитесь, что ваш сервер ClickHouse настроен на приём HTTP-соединений на порту, указанном в http_port. Например, если вы установили http_port = 8443, то ClickHouse должен прослушивать HTTP-запросы на порту 8443. Если вы используете внешнее промежуточное хранилище, вы можете опустить параметр http_port, поскольку clickhouse-connect не будет использоваться в этом случае.

Вы можете передать строку подключения к базе данных, аналогичную той, что используется библиотекой clickhouse-driver. Приведённые выше учётные данные будут выглядеть следующим образом:

# разместите это в начале вашего toml-файла, перед началом любых секций. \{#keep-it-at-the-top-of-your-toml-file-before-any-section-starts}
destination.clickhouse.credentials="clickhouse://dlt:Dlt*12345789234567@localhost:9000/dlt?secure=1"

Режим записи​

Поддерживаются все режимы записи.

Режимы записи в библиотеке dlt определяют, как следует записывать данные в целевое хранилище. Существует три типа режимов записи:

Replace: Этот режим заменяет данные в целевом хранилище данными из ресурса. Он удаляет все классы и объекты схемы и заново создаёт схему перед загрузкой данных. Подробнее об этом можно узнать здесь.

Merge: Этот режим записи объединяет данные из ресурса с данными в целевом хранилище. Для режима merge необходимо указать primary_key для ресурса. Подробнее об этом можно узнать здесь.

Append: Это режим по умолчанию. Он добавляет данные к существующим данным в целевом хранилище, игнорируя поле primary_key.

Загрузка данных​

Данные загружаются в ClickHouse с использованием наиболее эффективного метода в зависимости от источника данных:

  • Для локальных файлов используется библиотека clickhouse-connect для непосредственной загрузки файлов в таблицы ClickHouse с помощью команды INSERT.
  • Для файлов в удалённом хранилище, таком как S3, Google Cloud Storage или Azure Blob Storage, используются табличные функции ClickHouse, такие как s3, gcs и azureBlobStorage, для чтения файлов и загрузки данных в таблицы.

Наборы данных​

Clickhouse не поддерживает несколько наборов данных в одной базе данных, тогда как dlt по ряду причин основывается на концепции наборов данных. Чтобы Clickhouse корректно работал с dlt, имена таблиц, создаваемых dlt в вашей базе данных Clickhouse, будут начинаться с имени набора данных, разделённого настраиваемым dataset_table_separator. Кроме того, будет создана специальная сигнальная таблица, которая не содержит никаких данных и позволяет dlt распознавать, какие виртуальные наборы данных уже существуют в пункте назначения Clickhouse.

Поддерживаемые форматы файлов​

  • jsonl — предпочтительный формат как для прямой загрузки, так и для промежуточного хранения (staging).
  • parquet поддерживается как для прямой загрузки, так и для промежуточного хранения (staging).

Назначение (destination) clickhouse имеет несколько специфических отличий от стандартных SQL-назначений:

  1. В ClickHouse есть экспериментальный тип данных object, но на практике он ведёт себя несколько непредсказуемо, поэтому назначение dlt clickhouse будет загружать сложный тип данных в текстовый столбец. Если вам нужна эта возможность, присоединяйтесь к нашему сообществу в Slack, и мы рассмотрим её добавление.
  2. ClickHouse не поддерживает тип данных time. Значения времени будут загружаться в столбец типа text.
  3. ClickHouse не поддерживает тип данных binary. Вместо этого двоичные данные будут загружаться в столбец типа text. При загрузке из jsonl двоичные данные будут представлять собой строку в формате base64, а при загрузке из parquet объект binary будет преобразован в text.
  4. ClickHouse позволяет добавлять в уже заполненную таблицу столбцы с ограничением NOT NULL.
  5. ClickHouse при определённых условиях может давать ошибки округления при использовании типов данных float или double. Если для вас недопустимы ошибки округления, обязательно используйте тип данных decimal. Например, загрузка значения 12.7001 в столбец типа double при формате файлов загрузчика, установленном в jsonl, предсказуемо приведёт к ошибке округления.

Поддерживаемые подсказки для столбцов​

ClickHouse поддерживает следующие подсказки для столбцов:

  • primary_key — помечает столбец как часть первичного ключа. Для создания составного первичного ключа этой подсказкой можно пометить несколько столбцов.

Табличный движок​

По умолчанию таблицы создаются с использованием табличного движка ReplicatedMergeTree в ClickHouse. Вы можете указать другой табличный движок с помощью параметра table_engine_type в адаптере ClickHouse:

from dlt.destinations.adapters import clickhouse_adapter

@dlt.resource()
def my_resource():
  ...

clickhouse_adapter(my_resource, table_engine_type="merge_tree")

Поддерживаемые значения:

  • merge_tree — создаёт таблицы с использованием движка MergeTree
  • replicated_merge_tree (по умолчанию) — создаёт таблицы с использованием движка ReplicatedMergeTree

Поддержка промежуточного хранилища​

ClickHouse поддерживает Amazon S3, Google Cloud Storage и Azure Blob Storage в качестве целевых промежуточных хранилищ файлов.

dlt будет выгружать файлы Parquet или jsonl в промежуточное хранилище и использовать табличные функции ClickHouse для загрузки данных непосредственно из этих файлов.

Обратитесь к документации по файловой системе, чтобы узнать, как настроить учетные данные для промежуточных хранилищ:

Чтобы запустить конвейер с включённым промежуточным хранилищем:

pipeline = dlt.pipeline(
  pipeline_name='chess_pipeline',
  destination='clickhouse',
  staging='filesystem',  # add this to activate staging
  dataset_name='chess_data'
)

Использование Google Cloud Storage как промежуточного хранилища​

dlt поддерживает использование Google Cloud Storage (GCS) в качестве промежуточного хранилища при загрузке данных в ClickHouse. Это выполняется автоматически с помощью табличной функции GCS ClickHouse, которую dlt использует под капотом.

Табличная функция GCS ClickHouse поддерживает аутентификацию только с использованием ключей Hash-based Message Authentication Code (HMAC). Для этого GCS предоставляет режим совместимости с S3, эмулирующий API Amazon S3. ClickHouse использует это, чтобы получать доступ к бакетам GCS через свою интеграцию с S3.

Чтобы настроить промежуточное хранилище GCS с аутентификацией HMAC в dlt:

  1. Создайте HMAC-ключи для вашего сервисного аккаунта GCS, следуя руководству Google Cloud.

  2. Укажите HMAC-ключи, а также client_email, project_id и private_key для вашего сервисного аккаунта в настройках назначения ClickHouse вашего проекта dlt в файле config.toml:

[destination.filesystem]
bucket_url = "gs://dlt-ci"

[destination.filesystem.credentials]
project_id = "a-cool-project"
client_email = "my-service-account@a-cool-project.iam.gserviceaccount.com"
private_key = "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkaslkdjflasjnkdcopauihj...wEiEx7y+mx\nNffxQBqVVej2n/D93xY99pM=\n-----END PRIVATE KEY-----\n"

[destination.clickhouse.credentials]
database = "dlt"
username = "dlt"
password = "Dlt*12345789234567"
host = "localhost"
port = 9440
secure = 1
gcp_access_key_id = "JFJ$$*f2058024835jFffsadf"
gcp_secret_access_key = "DFJdwslf2hf57)%$02jaflsedjfasoi"

Примечание: В дополнение к HMAC‑ключам bashgcp_access_key_id и gcp_secret_access_key теперь нужно указать client_email, project_id и private_key для вашей учетной записи службы (service account) в секции [destination.filesystem.credentials]. Это связано с тем, что поддержка промежуточного размещения (staging) в GCS сейчас реализована как временное обходное решение и пока не оптимизирована.

dlt передаст эти учетные данные в ClickHouse, который будет отвечать за аутентификацию и доступ к GCS.

Ведётся активная работа по упрощению и улучшению настройки промежуточного размещения в GCS для назначения (destination) ClickHouse dlt в будущем. Полноценная поддержка GCS staging отслеживается в следующих задачах GitHub:

Поддержка dbt​

Интеграция с dbt в целом поддерживается через dbt-clickhouse.

Синхронизация состояния dlt​

Это назначение полностью поддерживает синхронизацию состояния dlt.