Intégrer Google Cloud Storage à ClickHouse Cloud

Connectez simplement votre stockage objet à ClickHouse Cloud.

Le ClickPipe GCS offre une solution entièrement gérée et résiliente pour ingérer des données depuis Google Cloud Storage (GCS). Il prend en charge l’ingestion ponctuelle et l’ingestion continue, avec une sémantique d’exactly-once.

Les GCS ClickPipes peuvent être déployés et gérés manuellement via l’interface utilisateur de ClickPipes, ainsi que de façon programmatique à l’aide d’OpenAPI et de Terraform.

​

Formats pris en charge

• JSON
• CSV
• TSV
• Parquet
• Avro

​

Fonctionnalités

​

Ingestion ponctuelle

Par défaut, le ClickPipe GCS charge en un seul lot tous les fichiers du bucket spécifié qui correspondent à un motif dans la table de destination ClickHouse. Une fois la tâche d’ingestion terminée, le ClickPipe s’arrête automatiquement. Ce mode d’ingestion ponctuelle offre une sémantique d’exactly-once, assurant que chaque fichier est traité de manière fiable, sans doublons.

​

Ingestion continue

Lorsque l’ingestion continue est activée, ClickPipes ingère en continu les données depuis le chemin spécifié. Pour déterminer l’ordre d’ingestion, le ClickPipe GCS s’appuie par défaut sur l’ordre lexicographique implicite des fichiers. Il peut également être configuré pour ingérer les fichiers dans n’importe quel ordre à l’aide d’un abonnement Google Cloud Pub/Sub configuré pour envoyer des notifications pour le bucket.

​

Ordre lexicographique

Le ClickPipe GCS suppose que les fichiers sont ajoutés à un bucket dans l’ordre lexicographique et s’appuie sur cet ordre implicite pour ingérer les fichiers séquentiellement. Cela signifie que tout nouveau fichier doit être lexicographiquement supérieur au dernier fichier ingéré. Par exemple, des fichiers nommés file1, file2 et file3 seront ingérés séquentiellement, mais si un nouveau file 0 est ajouté au bucket, il sera ignoré, car son nom n’est pas lexicographiquement supérieur à celui du dernier fichier ingéré.

Dans ce mode, le ClickPipe GCS effectue un chargement initial de tous les fichiers dans le chemin spécifié, puis recherche de nouveaux fichiers à intervalles configurables (30 secondes par défaut). Il est impossible de démarrer l’ingestion à partir d’un fichier spécifique ou d’un moment précis — ClickPipes chargera toujours tous les fichiers du chemin spécifié.

​

Dans n’importe quel ordre

Consultez Configurer le mode non ordonné pour l’ingestion continue pour obtenir des instructions étape par étape.

Il est possible de configurer un ClickPipe GCS pour ingérer des fichiers qui n’ont pas d’ordre implicite en configurant un abonnement Google Cloud Pub/Sub qui reçoit les notifications du bucket. Cela permet à ClickPipes d’écouter les événements de création d’objets et d’ingérer tout nouveau fichier, quelle que soit la convention de nommage utilisée.

Le mode non ordonné n’est pas pris en charge pour les buckets publics. Il nécessite une authentification par compte de service ainsi qu’un abonnement Google Cloud Pub/Sub connecté au bucket.

Dans ce mode, le ClickPipe GCS effectue un chargement initial de tous les fichiers du chemin sélectionné, puis écoute les notifications OBJECT_FINALIZE via l’abonnement Pub/Sub correspondant au chemin spécifié. Tout message concernant un fichier déjà traité, un fichier ne correspondant pas au chemin ou un événement d’un autre type sera ignoré. Il est impossible de démarrer l’ingestion à partir d’un fichier précis ou d’un moment donné : ClickPipes chargera toujours tous les fichiers du chemin sélectionné.

​

Correspondance des motifs de fichiers

Les Object Storage ClickPipes suivent la norme POSIX pour la correspondance des motifs de fichiers. Tous les motifs sont sensibles à la casse et s’appliquent au chemin complet après le nom du bucket. Pour de meilleures performances, utilisez le motif le plus spécifique possible (par exemple, data-2024-*.csv plutôt que *.csv).

​

Motifs pris en charge

Motif	Description	Exemple	Correspondances
?	Correspond à exactement un caractère (hors /)	data-?.csv	data-1.csv, data-a.csv, data-x.csv
*	Correspond à zéro, un ou plusieurs caractères (hors /)	data-*.csv	data-1.csv, data-001.csv, data-report.csv, data-.csv
** Récursif	Correspond à zéro, un ou plusieurs caractères (y compris /). Permet de parcourir les répertoires de manière récursive.	logs/**/error.log	logs/error.log, logs/2024/error.log, logs/2024/01/error.log

Exemples :

• https://bucket.s3.amazonaws.com/folder/*.csv
• https://bucket.s3.amazonaws.com/logs/**/data.json
• https://bucket.s3.amazonaws.com/file-?.parquet
• https://bucket.s3.amazonaws.com/data-2024-*.csv.gz

​

Motifs non pris en charge

Motif	Description	Exemple	Alternatives
{abc,def}	Expansion d’accolades (alternatives)	{logs,data}/file.csv	Créez des ClickPipes distincts pour chaque chemin.
{N..M}	Expansion de plage numérique	file-{1..100}.csv	Utilisez file-*.csv ou file-?.csv.

Exemples :

• https://bucket.s3.amazonaws.com/{documents-01,documents-02}.json
• https://bucket.s3.amazonaws.com/file-{1..100}.csv
• https://bucket.s3.amazonaws.com/{logs,metrics}/data.parquet

​

Sémantique d’« exactly-once »

Différents types de défaillances peuvent se produire lors de l’ingestion de grands jeux de données, ce qui peut entraîner des insertions partielles ou des doublons. Les Object Storage ClickPipes sont robustes face aux échecs d’insertion et offrent une sémantique d’« exactly-once ». Cela est rendu possible grâce à l’utilisation de tables de « staging » temporaires. Les données sont d’abord insérées dans les tables de staging. Si un problème survient pendant cette insertion, la table de staging peut être tronquée et l’insertion peut être relancée depuis un état propre. Ce n’est que lorsqu’une insertion est terminée avec succès que les partitions de la table de staging sont déplacées vers la table cible. Pour en savoir plus sur cette stratégie, consultez cet article de blog.

​

Colonnes virtuelles

Pour suivre les fichiers qui ont été ingérés, incluez la colonne virtuelle _file dans la liste de mappage des colonnes. La colonne virtuelle _file contient le nom de fichier de l’objet source, ce qui permet de savoir quels fichiers ont été traités.

​

Contrôle d’accès

​

Autorisations

Le ClickPipe GCS prend en charge les buckets publics et privés. Les buckets Requester Pays ne sont pas pris en charge.

​

GCS bucket

Le compte de service utilisé par ClickPipes doit disposer des autorisations suivantes au niveau du bucket :

• roles/storage.objectViewer

Ce rôle inclut les autorisations IAM storage.objects.list et `storage.objects.get, qui permettent à ClickPipes de répertorier et de récupérer les objets dans le bucket spécifié.

​

Abonnement Pub/Sub

Lors de l’utilisation du mode non ordonné, le compte de service doit disposer des rôles suivants pour l’abonnement Pub/Sub :

• roles/pubsub.subscriber — pour recevoir les messages et en accuser réception.
• roles/pubsub.viewer — pour obtenir les métadonnées de l’abonnement.

​

Authentification

​

Compte de service

L’authentification via un compte de service est requise lors de l’utilisation du mode non ordonné avec les notifications Pub/Sub. Sélectionnez Service Account comme méthode d’authentification, puis téléversez le fichier JSON de la clé du compte de service.

​

Identifiants HMAC

Pour utiliser des clés HMAC pour vous authentifier, sélectionnez Credentials sous Méthode d’authentification lors de la configuration de votre connexion ClickPipe. Renseignez ensuite la clé d’accès (par exemple, GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA) et la clé secrète (par exemple, bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ) dans Access key et Secret key, respectivement.

Suivez ce guide pour créer un compte de service avec une clé HMAC.

​

Accès réseau

Les ClickPipes GCS utilisent deux chemins réseau distincts pour la découverte des métadonnées et l’ingestion des données : le service ClickPipes et le service ClickHouse Cloud, respectivement. Si vous souhaitez ajouter une couche supplémentaire de sécurité réseau (par exemple, pour des raisons de conformité), l’accès réseau doit être configuré pour ces deux chemins.

• Pour le contrôle d’accès par adresse IP, les règles de filtrage IP de votre bucket GCS doivent autoriser les IP statiques de la région du service ClickPipes indiquées ici, ainsi que les IP statiques du service ClickHouse Cloud. Pour obtenir les IP statiques de votre région ClickHouse Cloud, ouvrez un terminal et exécutez :

  # Remplacez <your-region> par votre région ClickHouse Cloud
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.gcp[] | select(.region == "<your-region>") | .egress_ips[]'
  

​

Paramètres avancés

ClickPipes propose des valeurs par défaut adaptées à la plupart des cas d’utilisation. Si votre cas d’utilisation nécessite un réglage plus fin, vous pouvez ajuster les paramètres suivants :

Paramètre	Valeur par défaut	Description
Max insert bytes	10GB	Nombre d’octets à traiter dans un seul lot d’insertion.
Max file count	100	Nombre maximal de fichiers à traiter dans un seul lot d’insertion.
Max threads	auto(3)	Nombre maximal de threads concurrents pour le traitement des fichiers.
Max insert threads	1	Nombre maximal de threads d’insertion concurrents pour le traitement des fichiers.
Min insert block size bytes	1GB	Taille minimale en octets du bloc pouvant être inséré dans une table.
Max download threads	4	Nombre maximal de threads de téléchargement concurrents.
Object storage polling interval	30s	Configure le délai d’attente maximal avant l’insertion des données dans le cluster ClickHouse.
Parallel distributed insert select	2	Paramètre parallel distributed insert select.
Parallel view processing	false	Indique s’il faut activer l’envoi vers les vues attachées de manière concurrente plutôt que séquentielle.
Use cluster function	true	Indique s’il faut traiter les fichiers en parallèle sur plusieurs nœuds.

​

Mise à l’échelle

La mise à l’échelle des Object Storage ClickPipes repose sur la taille minimale du service ClickHouse, déterminée par les paramètres d’autoscaling vertical configurés. La taille du ClickPipe est définie au moment de la création du pipe. Les modifications ultérieures des paramètres du service ClickHouse n’affecteront pas la taille du ClickPipe.

Pour augmenter le débit des jobs d’ingestion volumineux, nous recommandons de mettre à l’échelle le service ClickHouse avant de créer le ClickPipe.

​

Limitations connues

​

Taille du fichier

ClickPipes n’essaiera d’ingérer que des objets d’une taille inférieure ou égale à 10 Go. Si un fichier dépasse 10 Go, une erreur sera ajoutée à la table d’erreurs dédiée de ClickPipes.

​

Compatibilité

Le ClickPipe GCS s’appuie sur l’API XML de Cloud Storage pour l’interopérabilité, ce qui impose d’utiliser le préfixe de bucket https://storage.googleapis.com/ (au lieu de gs://) ainsi que des clés HMAC pour l’authentification.

​

Prise en charge des vues

Les vues matérialisées sur la table cible sont également prises en charge. ClickPipes créera des tables de staging non seulement pour la table cible, mais aussi pour toute vue matérialisée dont elle dépend.

Nous ne créons pas de tables de staging pour les vues non matérialisées. Cela signifie que si vous avez une table cible avec une ou plusieurs vues matérialisées en aval, ces vues matérialisées doivent éviter de sélectionner des données via une vue à partir de la table cible. Sinon, il peut manquer des données dans la vue matérialisée.