Connecter dlt à ClickHouse

dlt est une bibliothèque open source que vous pouvez ajouter à vos scripts Python pour charger des données provenant de sources variées, souvent désordonnées, dans des jeux de données bien structurés et actualisés en temps réel.

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"                         # Le nom de la base de données que vous avez créée
username = "dlt"                         # Nom d'utilisateur ClickHouse ; la valeur par défaut est généralement "default"
password = "Dlt*12345789234567"          # Mot de passe ClickHouse, le cas échéant
host = "localhost"                       # Hôte du serveur ClickHouse
port = 9000                              # Port HTTP ClickHouse ; la valeur par défaut est 9000
http_port = 8443                         # Port HTTP à utiliser pour se connecter à l'interface HTTP du serveur ClickHouse. La valeur par défaut est 8443.
secure = 1                               # Définissez 1 si vous utilisez HTTPS, sinon 0.

[destination.clickhouse]
dataset_table_separator = "___"          # Séparateur des noms de table du dataset.

# gardez-la en haut de votre fichier toml, avant le début de toute section.
destination.clickhouse.credentials="clickhouse://dlt:Dlt*12345789234567@localhost:9000/dlt?secure=1"

Tous les modes d’écriture sont pris en charge.

Dans la bibliothèque dlt, les modes d’écriture définissent la manière dont les données doivent être écrites vers la destination. Il existe trois types de modes d’écriture :

Replace : Ce mode remplace les données dans la destination par les données de la ressource. Il supprime toutes les classes et tous les objets, puis recrée le schéma avant de charger les données. Vous pouvez en savoir plus à ce sujet ici.

Merge : Ce mode fusionne les données de la ressource avec celles déjà présentes dans la destination. Pour le mode merge, vous devez spécifier une primary_key pour la ressource. Vous pouvez en savoir plus à ce sujet ici.

Append : Il s’agit du mode par défaut. Il ajoute les données aux données existantes dans la destination, en ignorant le champ primary_key.

Les données sont chargées dans ClickHouse à l’aide de la méthode la plus efficace selon la source de données :

• Pour les fichiers locaux, la bibliothèque clickhouse-connect est utilisée pour charger directement les fichiers dans des tables ClickHouse à l’aide de la commande INSERT.
• Pour les fichiers stockés dans un stockage distant comme S3, Google Cloud Storage ou Azure Blob Storage, des fonctions de table ClickHouse comme s3, gcs et azureBlobStorage sont utilisées pour lire les fichiers et insérer les données dans des tables.

ClickHouse ne prend pas en charge plusieurs jeux de données dans une même base de données, alors que dlt s'appuie sur les jeux de données pour plusieurs raisons. Pour faire fonctionner ClickHouse avec dlt, les noms des tables générées par dlt dans votre base de données ClickHouse seront préfixés par le nom du jeu de données, séparé par le dataset_table_separator configurable. De plus, une table sentinelle spéciale, ne contenant aucune donnée, sera créée afin de permettre à dlt d'identifier quels jeux de données virtuels existent déjà dans une destination ClickHouse.

• jsonl est le format privilégié, aussi bien pour le chargement direct que pour le staging.
• parquet est pris en charge aussi bien pour le chargement direct que pour le staging.

La destination clickhouse présente quelques différences spécifiques par rapport aux destinations SQL par défaut :

1. ClickHouse dispose d'un type de données object expérimental, mais nous avons constaté qu'il est quelque peu imprévisible. La destination ClickHouse de dlt chargera donc ce type de données complexe dans une colonne de texte. Si vous avez besoin de cette fonctionnalité, contactez notre communauté Slack et nous envisagerons de l'ajouter.
2. ClickHouse ne prend pas en charge le type de données time. time sera chargé dans une colonne text.
3. ClickHouse ne prend pas en charge le type de données binary. À la place, les données binaires seront chargées dans une colonne text. Lors d'un chargement depuis jsonl, les données binaires seront stockées sous forme de chaîne base64, et lors d'un chargement depuis parquet, l'objet binary sera converti en text.
4. ClickHouse accepte l'ajout de colonnes non nulles à une table déjà remplie.
5. ClickHouse peut produire des erreurs d'arrondi dans certaines conditions lors de l'utilisation du type de données float ou double. Si vous ne pouvez pas tolérer d'erreurs d'arrondi, veillez à utiliser le type de données decimal. Par exemple, charger la valeur 12.7001 dans une colonne double avec le format de fichier du chargeur défini sur jsonl produira systématiquement une erreur d'arrondi.

ClickHouse prend en charge les indications de colonnes suivantes :

• primary_key - indique que la colonne fait partie de la clé primaire. Plusieurs colonnes peuvent avoir cette indication afin de créer une clé primaire composite.

Par défaut, les tables sont créées dans ClickHouse à l’aide du moteur de table ReplicatedMergeTree. Vous pouvez spécifier un autre moteur de table à l’aide de table_engine_type avec l’adapter ClickHouse :

from dlt.destinations.adapters import clickhouse_adapter

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

clickhouse_adapter(my_resource, table_engine_type="merge_tree")

Les valeurs prises en charge sont :

• merge_tree - crée des tables avec le moteur MergeTree
• replicated_merge_tree (par défaut) - crée des tables avec le moteur ReplicatedMergeTree

ClickHouse prend en charge Amazon S3, Google Cloud Storage et Azure Blob Storage comme destinations de staging pour les fichiers.

dlt chargera des fichiers Parquet ou jsonl vers l’emplacement de staging et utilisera les fonctions de table de ClickHouse pour charger directement les données depuis les fichiers placés dans la zone de staging.

Veuillez consulter la documentation du système de fichiers pour savoir comment configurer les identifiants d’accès pour les destinations de staging :

• Amazon S3
• Google Cloud Storage
• Azure Blob Storage

Pour exécuter un pipeline avec le staging activé :

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

dlt prend en charge l’utilisation de Google Cloud Storage (GCS) comme zone de staging lors du chargement de données dans ClickHouse. Cela est géré automatiquement par la fonction de table GCS de ClickHouse, que dlt utilise en arrière-plan.

La fonction de table GCS de ClickHouse ne prend en charge que l’authentification à l’aide de clés HMAC (Hash-based Message Authentication Code). Pour l’activer, GCS propose un mode de compatibilité S3 qui émule l’API Amazon S3. ClickHouse s’appuie sur ce mécanisme pour permettre l’accès aux buckets GCS via son intégration S3.

Pour configurer le staging GCS avec l’authentification HMAC dans dlt :

1. Créez des clés HMAC pour votre compte de service GCS en suivant le guide Google Cloud.

2. Configurez les clés HMAC, ainsi que client_email, project_id et private_key de votre compte de service, dans les paramètres de la destination ClickHouse de votre projet dlt dans 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"

Remarque : En plus des clés HMAC bashgcp_access_key_id et gcp_secret_access_key), vous devez désormais fournir client_email, project_id et private_key pour votre compte de service sous [destination.filesystem.credentials]. Cela s'explique par le fait que la prise en charge du staging GCS repose actuellement sur une solution de contournement temporaire et n'est pas encore optimisée.

dlt transmettra ces identifiants à ClickHouse, qui se chargera de l'authentification et de l'accès à GCS.

Des travaux sont en cours pour simplifier et améliorer à l'avenir la configuration du staging GCS pour la destination ClickHouse de dlt. La prise en charge complète du staging GCS fait l'objet d'un suivi dans ces issues GitHub :

• Faire fonctionner la destination filesystem avec GCS en mode de compatibilité S3
• Prise en charge de la zone de staging Google Cloud Storage

L’intégration à dbt est généralement assurée via dbt-clickhouse.

Cette destination prend entièrement en charge la synchronisation de l’état de dlt.