Integración de Amazon S3 con ClickHouse Cloud

Conecte fácilmente su almacenamiento de objetos a ClickHouse Cloud.

S3 ClickPipe ofrece una forma totalmente gestionada y robusta de ingestar datos desde Amazon S3 y almacenes de objetos compatibles con S3 en ClickHouse Cloud. Admite tanto la ingestión única como la ingestión continua, con semántica de exactly-once.

Los S3 ClickPipes pueden desplegarse y gestionarse manualmente mediante la UI de ClickPipes, así como de forma programática con OpenAPI y Terraform.

​

Fuentes de datos compatibles

Nombre	Logo	Detalles
Amazon S3		La ingestión continua requiere orden lexicográfico de forma predeterminada, pero puede configurarse para ingestar archivos en cualquier orden.
Cloudflare R2 Compatible con S3		La ingestión continua requiere orden lexicográfico. El modo no ordenado no es compatible.
DigitalOcean Spaces Compatible con S3		La ingestión continua requiere orden lexicográfico. El modo no ordenado no es compatible.
OVH Object Storage Compatible con S3		La ingestión continua requiere orden lexicográfico. El modo no ordenado no es compatible.

Debido a las diferencias en los formatos de URL y las implementaciones de API entre los proveedores de servicios de almacenamiento de objetos, no todos los servicios compatibles con S3 son compatibles de inmediato. Si tienes problemas con un servicio que no aparece en la lista anterior, ponte en contacto con nuestro equipo.

​

Formatos compatibles

• JSON
• CSV
• TSV
• Parquet
• Avro

​

Funciones

​

Ingestión única

De forma predeterminada, el S3 ClickPipe carga todos los archivos que coinciden con un patrón del bucket especificado en la tabla de destino de ClickHouse en una sola operación por lotes. Una vez completada la tarea de ingestión, el ClickPipe se detiene automáticamente. Este modo de ingestión única ofrece semántica exactly-once, lo que garantiza que cada archivo se procese de forma fiable y sin duplicados.

​

Ingestión continua

Cuando la ingestión continua está habilitada, ClickPipes ingesta datos continuamente desde la ruta especificada. Para determinar el orden de ingestión, S3 ClickPipe se basa, de forma predeterminada, en el orden lexicográfico implícito de los archivos. También puede configurarse para ingestar archivos en cualquier orden mediante una cola de Amazon SQS conectada al bucket.

​

Orden lexicográfico

De forma predeterminada, el S3 ClickPipe asume que los archivos se añaden a un bucket en orden lexicográfico y se basa en ese orden implícito para ingestar los archivos de forma secuencial. Esto significa que cualquier archivo nuevo debe ser lexicográficamente mayor que el último archivo ingestado. Por ejemplo, los archivos llamados file1, file2 y file3 se ingestarán secuencialmente, pero si se añade un nuevo file 0 al bucket, se ignorará porque el nombre del archivo no es lexicográficamente mayor que el del último archivo ingestado.

En este modo, el S3 ClickPipe realiza una carga inicial de todos los archivos de la ruta especificada y luego consulta periódicamente si hay archivos nuevos en un intervalo configurable (de forma predeterminada, 30 segundos). Para iniciar la ingestión continua después de un archivo específico, configure Start after. ClickPipes omitirá los archivos que sean lexicográficamente menores o iguales que el valor configurado y continuará ingestando archivos más recientes a partir de ese punto.

​

En cualquier orden

Consulta Configurar el modo no ordenado para la ingestión continua para ver instrucciones paso a paso.

Es posible configurar un S3 ClickPipe para ingestar archivos que no tengan un orden implícito mediante la configuración de una cola de Amazon SQS conectada al bucket, opcionalmente con Amazon EventBridge como enrutador de eventos. Esto permite que ClickPipes escuche eventos de creación de objetos e ingeste archivos nuevos independientemente de la convención de nomenclatura.

El modo no ordenado solo es compatible con Amazon S3 y no es compatible con buckets públicos ni con servicios compatibles con S3. Requiere configurar una cola de Amazon SQS conectada al bucket, opcionalmente con Amazon EventBridge como enrutador de eventos.

En este modo, el S3 ClickPipe realiza una carga inicial de todos los archivos de la ruta seleccionada y luego escucha eventos ObjectCreated:* en la cola que coincidan con la ruta especificada. Cualquier mensaje de un archivo ya visto, de un archivo que no coincida con la ruta o de un evento de otro tipo se ignorará. Para ingerir solo archivos entregados a través de la cola, habilita Omitir carga inicial. Cuando está habilitado, ClickPipes omite el análisis inicial de los archivos existentes en la ruta seleccionada y procesa solo los archivos entregados a través de la cola de SQS.

Configurar un prefijo/sufijo para los eventos es opcional. Si lo haces, asegúrate de que coincida con la ruta configurada para el ClickPipe. S3 no permite múltiples reglas de notificación superpuestas para los mismos tipos de eventos.

Los archivos se ingieren cuando se alcanza el umbral configurado en max insert bytes o max file count, o después de un intervalo configurable (30 segundos de forma predeterminada). Si se configura una DLQ, los mensajes fallidos se volverán a encolar y se reprocesarán hasta el número de veces configurado en el parámetro maxReceiveCount de la DLQ.

Recomendamos encarecidamente configurar una Dead-Letter-Queue (DLQ) para la cola de SQS, para facilitar la depuración y el reintento de mensajes fallidos.

De EventBridge a SQS

También es posible enviar notificaciones de eventos de S3 a SQS a través de Amazon EventBridge. Este es el enfoque recomendado para la mayoría de los casos de uso, ya que EventBridge permite un filtrado de eventos más avanzado, la distribución a múltiples destinos y no está sujeto a la limitación de S3 de una sola regla de notificación por tipo de evento y prefijo. Consulta Configuración del modo no ordenado para la ingestión continua para obtener instrucciones paso a paso.

SNS a SQS

También es posible enviar notificaciones de eventos de S3 a SQS a través de un tema de SNS. Esto puede resultar útil si te encuentras con alguna de las limitaciones de la integración directa de S3 → SQS. En este caso, tendrás que habilitar la opción de entrega de mensajes sin formato.

​

Coincidencia de patrones de archivos

Object Storage ClickPipes siguen el estándar POSIX para la coincidencia de patrones de archivos. Todos los patrones son sensibles a mayúsculas y minúsculas y coinciden con la ruta completa después del nombre del bucket. Para mejorar el rendimiento, use el patrón más específico posible (p. ej., data-2024-*.csv en lugar de *.csv).

​

Patrones compatibles

Patrón	Descripción	Ejemplo	Coincidencias
?	Coincide con exactamente un carácter (excepto /)	data-?.csv	data-1.csv, data-a.csv, data-x.csv
*	Coincide con cero o más caracteres (excepto /)	data-*.csv	data-1.csv, data-001.csv, data-report.csv, data-.csv
** Recursivo	Coincide con cero o más caracteres (incluido /). Permite el recorrido recursivo de directorios.	logs/**/error.log	logs/error.log, logs/2024/error.log, logs/2024/01/error.log

Ejemplos:

• 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

​

Patrones no admitidos

Patrón	Descripción	Ejemplo	Alternativas
{abc,def}	Expansión entre llaves.	{logs,data}/file.csv	Cree ClickPipes independientes para cada ruta.
{N..M}	Expansión de rango numérico	file-{1..100}.csv	Use file-*.csv o file-?.csv.

Ejemplos:

• 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

​

Semántica de exactly-once

Pueden producirse varios tipos de fallos al ingestar grandes conjuntos de datos, lo que puede dar lugar a inserciones parciales o datos duplicados. Object Storage ClickPipes es resiliente ante fallos de inserción y proporciona semántica de exactly-once. Esto se consigue mediante tablas temporales de “staging”. Los datos se insertan primero en las tablas de staging. Si algo sale mal durante esta inserción, la tabla de staging puede truncarse y la inserción puede reintentarse desde un estado limpio. Solo cuando una inserción se completa correctamente, las particiones de la tabla de staging se mueven a la tabla de destino. Para obtener más información sobre esta estrategia, consulta esta entrada del blog.

​

Columnas virtuales

Para hacer un seguimiento de qué archivos se han ingerido, incluya la columna virtual _file en la lista de asignación de columnas. La columna virtual _file contiene el nombre de archivo del objeto de origen, que puede utilizarse para consultar qué archivos se han procesado.

​

Control de acceso

​

Permisos

El S3 ClickPipe admite buckets públicos y privados. Los buckets con Requester Pays no son compatibles.

​

Bucket de S3

Los buckets deben permitir las siguientes acciones en la política del bucket:

• s3:GetObject
• s3:ListBucket

​

Cola de SQS

Al usar el modo no ordenado, SQS debe permitir las siguientes acciones en la política de la cola:

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

​

Autenticación

​

Credenciales de IAM

Para usar claves de acceso para autenticarse, selecciona Credentials en Método de autenticación al configurar tu conexión de ClickPipe. Luego, introduce el ID de la clave de acceso (por ejemplo, AKIAIOSFODNN7EXAMPLE) y la clave de acceso secreta (por ejemplo, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY) en Access key y Secret key, respectivamente.

​

IAM role

Para usar acceso basado en roles para autenticarse, selecciona IAM role en Método de autenticación al configurar tu conexión de ClickPipe.

Sigue esta guía para crear un rol con la política de confianza necesaria para acceder a S3. Luego, indica el ARN del rol de IAM en IAM role ARN.

​

Acceso de red

Los ClickPipes de S3 usan dos rutas de red distintas para el descubrimiento de metadatos y la ingestión de datos: el servicio ClickPipes y el servicio ClickHouse Cloud, respectivamente. Si desea configurar una capa adicional de seguridad de red (por ejemplo, por motivos de cumplimiento normativo), el acceso de red debe configurarse para ambas rutas.

• Para el control de acceso basado en IP, la política del bucket de S3 debe permitir las IP estáticas de la región del servicio ClickPipes indicadas aquí, así como las IP estáticas del servicio ClickHouse Cloud. Para obtener las IP estáticas de su región de ClickHouse Cloud, abra una terminal y ejecute:

  # Reemplace <your-region> por su región de ClickHouse Cloud
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .egress_ips[]'
  

• Para el control de acceso basado en endpoints de VPC, el bucket de S3 debe estar en la misma región que el servicio ClickHouse Cloud y restringir las operaciones GetObject a los ID de los endpoints de VPC del servicio ClickHouse Cloud. Para obtener los endpoints de VPC de su región de ClickHouse Cloud, abra una terminal y ejecute:

  # Reemplace <your-region> por su región de ClickHouse Cloud
  curl -s https://api.clickhouse.cloud/static-ips.json | jq -r '.aws[] | select(.region == "<your-region>") | .s3_endpoints[]'
  

​

Configuración avanzada

ClickPipes ofrece valores predeterminados adecuados para cubrir los requisitos de la mayoría de los casos de uso. Si su caso de uso requiere un ajuste más fino, puede modificar la siguiente configuración:

Configuración	Valor predeterminado	Descripción
Max insert bytes	10GB	Número de bytes que se procesan en un único lote de inserción.
Max file count	100	Número máximo de archivos que se procesan en un único lote de inserción.
Max threads	auto(3)	Número máximo de hilos concurrentes para el procesamiento de archivos.
Max insert threads	1	Número máximo de hilos de inserción concurrentes para el procesamiento de archivos.
Min insert block size bytes	1GB	Tamaño mínimo, en bytes, del bloque que se puede insertar en una tabla.
Max download threads	4	Número máximo de hilos de descarga concurrentes.
Object storage polling interval	30s	Configura el período máximo de espera antes de insertar datos en el clúster de ClickHouse.
Start after	None	Para la ingestión continua ordenada, omite los archivos lexicográficamente menores o iguales que el nombre de archivo o la ruta configurados.
Skip initial load	false	Para la ingestión continua no ordenada, omite el análisis inicial de los archivos existentes y procesa únicamente las notificaciones de objetos de la cola de SQS configurada.
Parallel distributed insert select	2	Configuración de inserción distribuida paralela con select.
Parallel view processing	false	Indica si se habilita el envío a vistas adjuntas de forma concurrente en lugar de secuencial.
Use cluster function	true	Indica si los archivos se procesan en paralelo en varios nodos.

​

Escalado

Object Storage ClickPipes se escalan en función del tamaño mínimo del servicio de ClickHouse determinado por la configuración del escalado automático vertical. El tamaño del ClickPipe se determina cuando se crea el pipe. Los cambios posteriores en la configuración del servicio de ClickHouse no afectarán al tamaño del ClickPipe.

Para aumentar el rendimiento en trabajos de ingesta de gran volumen, recomendamos escalar el servicio de ClickHouse antes de crear el ClickPipe.

​

Limitaciones conocidas

​

Tamaño del archivo

ClickPipes solo intentará ingestar objetos de 10GB o menos. Si un archivo supera los 10GB, se añadirá un error a la tabla de errores dedicada de ClickPipes.

​

Compatibilidad

Aunque son compatibles con S3, algunos servicios usan una estructura de URL distinta que S3 ClickPipe podría no ser capaz de interpretar (por ejemplo, Backblaze B2), o requieren integración con servicios de cola específicos del proveedor para una ingestión continua y sin orden. Si tiene problemas con un servicio que no aparece en Fuentes de datos compatibles, póngase en contacto con nuestro equipo.

​

Compatibilidad con vistas

También se admiten vistas materializadas sobre la tabla de destino. ClickPipes creará tablas de staging no solo para la tabla de destino, sino también para cualquier vista materializada dependiente.

No creamos tablas de staging para vistas no materializadas. Esto significa que, si tiene una tabla de destino con una o más vistas materializadas aguas abajo, esas vistas materializadas deben evitar seleccionar datos a través de una vista sobre la tabla de destino. De lo contrario, es posible que falten datos en la vista materializada.