Intégrer Amazon S3 à ClickHouse Cloud

Le S3 ClickPipe offre une solution entièrement gérée et résiliente pour ingérer des données depuis Amazon S3 et des stockages objet compatibles S3 dans ClickHouse Cloud. Il prend en charge l’ingestion ponctuelle et l’ingestion continue, avec une garantie d’exactement une fois.

Les S3 ClickPipes peuvent être déployés et gérés manuellement à l’aide de la ClickPipes UI, ainsi que par programmation à l’aide d’OpenAPI et de Terraform.

Nom	Logo	Détails
Amazon S3		L’ingestion continue nécessite par défaut un ordre lexicographique, mais peut être configurée pour ingérer des fichiers dans n’importe quel ordre.
Cloudflare R2 compatible avec S3		L’ingestion continue nécessite un ordre lexicographique. Le mode non ordonné n’est pas pris en charge.
DigitalOcean Spaces compatible avec S3		L’ingestion continue nécessite un ordre lexicographique. Le mode non ordonné n’est pas pris en charge.
OVH Object Storage compatible avec S3		L’ingestion continue nécessite un ordre lexicographique. Le mode non ordonné n’est pas pris en charge.

• JSON
• CSV
• TSV
• Parquet
• Avro

Par défaut, le S3 ClickPipe charge, en une seule opération groupée, 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 garantie d’exactement une fois, de sorte que chaque fichier soit traité de manière fiable, sans doublon.

Lorsque l’ingestion continue est activée, ClickPipes ingère en continu les données à partir du chemin spécifié. Pour déterminer l’ordre d’ingestion, le S3 ClickPipe 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’une file d’attente Amazon SQS connectée au bucket.

Par défaut, le S3 ClickPipe 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 S3 ClickPipe effectue un chargement initial de tous les fichiers dans le chemin spécifié, puis recherche de nouveaux fichiers à un intervalle configurable (par défaut, 30 secondes). Pour démarrer l’ingestion continue après un fichier spécifique, configurez Démarrer après. ClickPipes ignorera les fichiers lexicographiquement inférieurs ou égaux à la valeur configurée et continuera à ingérer les fichiers plus récents à partir de ce point.

Il est possible de configurer un S3 ClickPipe pour ingérer des fichiers qui n’ont pas d’ordre implicite en configurant une file d’attente Amazon SQS connectée au bucket, avec éventuellement Amazon EventBridge comme routeur d’événements. Cela permet à ClickPipes d’écouter les événements de création d’objet et d’ingérer tous les nouveaux fichiers, quelle que soit leur convention de nommage.

Dans ce mode, le S3 ClickPipe effectue un chargement initial de tous les fichiers dans le chemin sélectionné, puis écoute dans la file d’attente les événements ObjectCreated:* correspondant au chemin spécifié. Tout message concernant un fichier déjà vu, un fichier ne correspondant pas au chemin ou un événement d’un autre type sera ignoré. Pour ingérer uniquement les fichiers transmis via la file d’attente, activez Ignorer le chargement initial. Lorsqu’il est activé, ClickPipes ignore le parcours initial des fichiers existants dans le chemin sélectionné et traite uniquement les fichiers transmis via la file d’attente SQS.

Les fichiers sont ingérés une fois le seuil configuré dans max insert bytes ou max file count atteint, ou après un intervalle configurable (30 secondes par défaut). Si une DLQ est configurée, les messages en échec seront remis dans la file d’attente et retraités jusqu’au nombre de tentatives défini dans le paramètre maxReceiveCount de la DLQ.

Il est également possible d’envoyer des notifications d’événements S3 à SQS via Amazon EventBridge. Il s’agit de l’approche recommandée dans la plupart des cas d’utilisation, car EventBridge offre un filtrage des événements plus avancé, une diffusion vers plusieurs cibles, et n’est pas soumis à la limitation de S3 qui n’autorise qu’une seule règle de notification par type d’événement et par préfixe. Consultez Configurer le mode non ordonné pour l’ingestion continue pour obtenir des instructions étape par étape.

Il est également possible d’envoyer des notifications d’événements S3 à SQS via un topic SNS. Cela peut être utile si vous atteignez certaines des limites de l’intégration directe entre S3 et SQS. Dans ce cas, vous devrez activer l’option raw message delivery.

Les Object Storage ClickPipes suivent la norme POSIX pour la correspondance des motifs de fichiers. Tous les motifs respectent la casse et correspondent 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 au lieu de *.csv).

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

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

Différents types de défaillances peuvent survenir 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 résistent aux échecs d'insertion et offrent une garantie d'exactement une fois. 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 quelque chose se passe mal pendant cette insertion, la table de staging peut être tronquée et l'insertion peut être relancée à partir d'un état propre. Ce n'est qu'une fois l'insertion 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.

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 d’identifier par requête quels fichiers ont été traités.

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

Les buckets doivent autoriser les actions suivantes dans la politique du bucket :

• s3:GetObject
• s3:ListBucket

Lors de l’utilisation du mode non ordonné, SQS doit autoriser les actions suivantes dans la politique de la file d’attente :

• sqs:ReceiveMessage
• sqs:DeleteMessage
• sqs:GetQueueAttributes
• sqs:ListQueues

Pour utiliser des clés d'accès pour vous authentifier, sélectionnez Credentials sous Méthode d’authentification lors de la configuration de votre connexion ClickPipe. Indiquez ensuite l'ID de clé d'accès (par exemple, AKIAIOSFODNN7EXAMPLE) et la clé d'accès secrète (par exemple, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY) dans les champs Access key et Secret key, respectivement.

Pour utiliser le contrôle d’accès basé sur les rôles pour vous authentifier, choisissez IAM role sous Méthode d’authentification lors de la configuration de votre connexion ClickPipe.

Suivez ce guide pour créer un rôle avec la stratégie d’approbation requise pour accéder à S3. Indiquez ensuite l’ARN du rôle IAM dans IAM role ARN.

Les S3 ClickPipes utilisent deux chemins réseau distincts, respectivement pour la découverte des métadonnées et pour l'ingestion des données : le service ClickPipes et le service ClickHouse Cloud. Si vous souhaitez ajouter un niveau 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 basé sur les IP, la politique du bucket S3 doit 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 '.aws[] | select(.region == "<your-region>") | .egress_ips[]'

• Pour le contrôle d'accès basé sur les VPC endpoints, le bucket S3 doit se trouver dans la même région que le service ClickHouse Cloud et restreindre les opérations GetObject aux identifiants de VPC endpoint du service ClickHouse Cloud. Pour obtenir les VPC endpoints 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 '.aws[] | select(.region == "<your-region>") | .s3_endpoints[]'

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

Les Object Storage ClickPipes sont mis à l’échelle en fonction de la taille minimale du service ClickHouse, déterminée par les paramètres d’autoscaling vertical configurés. La taille du ClickPipe est déterminée lors 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 vous recommandons de mettre à l’échelle le service ClickHouse avant de créer le ClickPipe.

ClickPipes tentera uniquement d’ingérer les objets de 10 Go ou moins. Si un fichier dépasse 10 Go, une erreur sera ajoutée à la table d’erreurs dédiée de ClickPipes.

Bien que compatibles avec S3, certains services utilisent une structure d'URL différente que le S3 ClickPipe peut ne pas parvenir à analyser (par exemple, Backblaze B2), ou nécessitent une intégration avec des services de file d'attente propres au fournisseur pour une ingestion continue non ordonnée. Si vous rencontrez des problèmes avec un service qui ne figure pas parmi les sources de données prises en charge, veuillez contacter notre équipe.

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 qui en 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 par l’intermédiaire d’une vue à partir de la table cible. Sinon, il est possible que des données soient manquantes dans la vue matérialisée.