Integración de Google Cloud Storage con ClickHouse Cloud

El ClickPipe de GCS proporciona una forma totalmente gestionada y resiliente de ingestar datos desde Google Cloud Storage (GCS). Admite tanto la ingestión única como la ingestión continua con semántica de exactly-once.

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

• JSON
• CSV
• TSV
• Parquet
• Avro

De forma predeterminada, el ClickPipe de GCS cargará en la tabla de destino de ClickHouse todos los archivos del bucket especificado que coincidan con un patrón, 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 de exactly-once, lo que garantiza que cada archivo se procese de forma fiable y sin duplicados.

Cuando la ingestión continua está activada, ClickPipes realiza la ingestión continua de datos desde la ruta especificada. Para determinar el orden de ingestión, el ClickPipe de GCS 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 suscripción de Google Cloud Pub/Sub configurada para proporcionar notificaciones del bucket.

El ClickPipe de GCS asume que los archivos se agregan a un bucket en orden lexicográfico y se basa en ese orden implícito para ingestar los archivos secuencialmente. 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 agrega 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 ClickPipe de GCS realiza una carga inicial de todos los archivos de la ruta especificada y luego sondea en busca de archivos nuevos a un intervalo configurable (de forma predeterminada, cada 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 nuevos a partir de ese punto.

Es posible configurar un ClickPipe de GCS para ingestar archivos que no tengan un orden implícito mediante la configuración de una suscripción de Google Cloud Pub/Sub que reciba notificaciones del bucket. Esto permite a ClickPipes detectar eventos de creación de objetos e ingestar cualquier archivo nuevo, independientemente de la convención de nombres.

En este modo, el ClickPipe de GCS realiza una carga inicial de todos los archivos de la ruta seleccionada y, a continuación, escucha notificaciones OBJECT_FINALIZE a través de la suscripción de Pub/Sub que coincidan con la ruta especificada. Cualquier mensaje correspondiente a un archivo ya visto, a un archivo que no coincida con la ruta o a un evento de otro tipo se ignorará. Para ingerir solo los archivos entregados a través de la suscripción, habilita Skip initial load. Cuando está habilitado, ClickPipes omite el escaneo inicial de los archivos existentes en la ruta seleccionada y procesa solo los archivos entregados a través de la suscripción de Pub/Sub.

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

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

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

Pueden producirse varios tipos de fallos al ingestar un conjunto de datos grande, lo que puede dar lugar a inserciones parciales o datos duplicados. Object Storage ClickPipes es resistente a los fallos de inserción y ofrece 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.

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

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

La cuenta de servicio que utiliza ClickPipes debe permitir las siguientes acciones a nivel del bucket:

• roles/storage.objectViewer

Este rol incluye los permisos de IAM storage.objects.list y `storage.objects.get, que permiten a ClickPipes listar y recuperar objetos en el bucket especificado.

Al usar modo no ordenado, la cuenta de servicio debe tener los siguientes roles en la suscripción de Pub/Sub:

• roles/pubsub.subscriber — para recibir y confirmar la recepción de mensajes.
• roles/pubsub.viewer — para obtener los metadatos de la suscripción.

La autenticación mediante cuenta de servicio es obligatoria cuando se usa el modo no ordenado con notificaciones de Pub/Sub. Seleccione Service Account como método de autenticación y cargue el archivo JSON de la clave de la cuenta de servicio.

Para usar claves HMAC para autenticarte, selecciona Credentials en Authentication method al configurar tu conexión de ClickPipe. Luego, proporciona la clave de acceso (p. ej., GOOGTS7C7FUP3AIRVJTE2BCDKINBTES3HC2GY5CBFJDCQ2SYHV6A6XXVTJFSA) y la clave secreta (p. ej., bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ) en Access key y Secret key, respectivamente.

Sigue esta guía para crear una cuenta de servicio con una clave HMAC.

Los ClickPipes de GCS utilizan 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, las reglas de filtrado de IP de su bucket de GCS deben 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:

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

ClickPipes proporciona 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:

Object Storage ClickPipes se escalan en función del tamaño mínimo del servicio de ClickHouse, determinado por la configuración de escalado vertical automático. 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 el 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.

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

El ClickPipe de GCS utiliza la API XML de Cloud Storage para la interoperabilidad, lo que requiere usar el prefijo de bucket https://storage.googleapis.com/ (en lugar de gs://) y claves HMAC para la autenticación.

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

No creamos tablas de staging para las 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 basada en la tabla de destino. De lo contrario, es posible que falten datos en la vista materializada.