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

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

pip install "dlt[clickhouse]"

dlt init chess clickhouse

pip install -r requirements.txt

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;

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

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

# оставьте это в верхней части toml-файла, до начала любых секций.
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 — предпочтительный формат как для прямой загрузки, так и для промежуточного хранилища.
• parquet поддерживается как для прямой загрузки, так и для промежуточного хранилища.

У пункта назначения clickhouse есть несколько особенностей по сравнению со стандартными SQL-пунктами назначения:

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

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

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

По умолчанию в ClickHouse таблицы создаются с движком таблицы ReplicatedMergeTree. Вы можете указать другой движок таблицы с помощью параметра 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 для загрузки данных напрямую из этих файлов.

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

• Amazon S3
• Google Cloud Storage
• Azure Blob Storage

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

pipeline = dlt.pipeline(
  pipeline_name='chess_pipeline',
  destination='clickhouse',
  staging='filesystem',  # добавьте это для активации промежуточного хранилища
  dataset_name='chess_data'
)

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 для вашего сервисного аккаунта в разделе [destination.filesystem.credentials]. Это связано с тем, что поддержка промежуточного хранилища GCS сейчас реализована как временное обходное решение и пока не оптимизирована.

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

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

• Обеспечить, чтобы пункт назначения filesystem работал с GCS в режиме совместимости с S3
• Поддержка промежуточного хранилища Google Cloud Storage

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

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