Integración de Google Pub/Sub con ClickHouse Cloud

Conecta sin problemas tus temas de Google Cloud Pub/Sub a ClickHouse Cloud.

Puedes inscribirte en la lista de espera de la Private Preview aquí.

Los ClickPipes de Pub/Sub se pueden desplegar y administrar manualmente desde la UI de ClickPipes, así como mediante programación con OpenAPI y Terraform.

​

Requisito previo

Ya se ha familiarizado con la introducción a ClickPipes, tiene acceso a un proyecto de GCP que contiene el tema desde el que desea ingestar y ha creado una cuenta de servicio con los permisos adecuados de Pub/Sub. Siga la guía de permisos de IAM para Pub/Sub para conocer el conjunto exacto de permisos que requiere ClickPipes.

​

Crear tu primer ClickPipe

1. Accede a la SQL Console de tu servicio de ClickHouse Cloud.

2. Selecciona el botón Data Sources en el menú lateral izquierdo y haz clic en “Set up a ClickPipe”

3. Selecciona GCP Pub/Sub como fuente de datos.

4. Completa el formulario asignándole un nombre a tu ClickPipe, indicando tu ID del proyecto de GCP y el archivo JSON de la cuenta de servicio de la cuenta de servicio a la que se le haya concedido acceso a Pub/Sub. El ID del proyecto debe tener entre 6 y 30 caracteres, puede contener letras minúsculas, dígitos y guiones, debe comenzar con una letra y no puede terminar con un guion.

5. Selecciona el tema de Pub/Sub desde el que ingestar. La lista desplegable se rellena automáticamente con los temas de tu proyecto de GCP (ordenados alfabéticamente) una vez validadas tus credenciales.

   • Formato de datos. ClickPipes consulta el registro de esquemas de Pub/Sub cuando seleccionas un tema. Si el tema tiene asociado un esquema Avro o Protobuf nativo, el formato de datos y el esquema se detectan automáticamente, y los selectores quedan fijados al esquema más reciente del tema. Los temas sin un esquema nativo usan JSONEachRow de forma predeterminada.
   • Offset inicial. Elige desde dónde comenzar a consumir. Las opciones disponibles son Latest (solo mensajes nuevos), Earliest (los mensajes retenidos más antiguos) y Seek to Timestamp (con un selector de fecha y hora en UTC).
   • Expresión de filtro (opcional). Un filtro de suscripción de Pub/Sub sobre atributos del mensaje; por ejemplo, attributes.type = "telemetry". Los filtros se aplican solo a los atributos del mensaje, no al payload, y no pueden cambiarse después de crear el pipe (para cambiar el filtro, es necesario volver a crear el pipe).
   • La UI mostrará un mensaje de muestra del tema seleccionado, con un interruptor Flatten object que te permite obtener una vista previa de cómo se aplanaría el JSON anidado en el destino.

6. En el siguiente paso, puedes elegir si quieres ingestar datos en una tabla nueva de ClickHouse o reutilizar una existente. Sigue las instrucciones en pantalla para modificar el nombre de la tabla, el esquema y la configuración. Puedes ver una vista previa en tiempo real de tus cambios en la tabla de ejemplo de la parte superior.

También puedes personalizar la configuración avanzada usando los controles proporcionados

7. Como alternativa, puedes decidir ingestar tus datos en una tabla de ClickHouse existente. En ese caso, la UI te permitirá mapear campos desde el origen a los campos de ClickHouse de la tabla de destino seleccionada.

8. Por último, puedes configurar los permisos del usuario interno de ClickPipes.

Permisos: ClickPipes creará un usuario dedicado para escribir datos en una tabla de destino. Puedes seleccionar un rol para este usuario interno usando un rol personalizado o uno de los roles predefinidos:

• Full access: con acceso completo al clúster. Puede ser útil si usas una vista materializada o un Diccionario con la tabla de destino.
  • Only destination table: con permisos INSERT solo sobre la tabla de destino.

9. Al hacer clic en “Complete Setup”, el sistema registrará tu ClickPipe y podrás verlo en la tabla de resumen.

La tabla de resumen ofrece controles para mostrar datos de ejemplo de la tabla de origen o de la tabla de destino en ClickHouse

Además, ofrece controles para eliminar el ClickPipe y mostrar un resumen de la tarea de ingestión.

10. ¡Enhorabuena! Has configurado correctamente tu primer ClickPipe de Pub/Sub. Se ejecutará de forma continua, ingestando datos en tiempo real desde tu tema de Pub/Sub a tu servicio de ClickHouse Cloud.

​

Suscripciones administradas

Los mensajes de Pub/Sub se consumen a través de suscripciones, no directamente desde los temas. ClickPipes crea y administra una suscripción dedicada para cada pipe; usted solo tiene que seleccionar un tema.

• La suscripción administrada se llama clickpipes-{pipeID} y se crea en el tema cuando se inicia el pipe.
• Está configurada con un ack deadline de 60 segundos, retención de mensajes de 7 días y ordenación de mensajes activada.
• La creación de la suscripción es idempotente; los reinicios del pipe y las reprogramaciones de la réplica reutilizan una suscripción existente si ya apunta al tema configurado.
• Durante el descubrimiento de temas y el muestreo de mensajes, ClickPipes también crea suscripciones efímeras de corta duración (clickpipes-discovery-{uuid}), que se eliminan inmediatamente después de que finaliza el muestreo.
• Cuando se elimina el pipe, ClickPipes elimina la suscripción administrada como parte del proceso de desmantelamiento.

Por lo tanto, la cuenta de servicio que proporcione debe tener permiso para crear y eliminar suscripciones en el proyecto, además de consumir mensajes desde ellas. Consulte la guía de permisos de IAM de Pub/Sub para ver la lista completa.

​

Formatos de datos compatibles

Los formatos compatibles son:

• JSON
• Avro — mediante esquemas nativos de Pub/Sub (codificación BINARY)
• Protobuf — mediante esquemas nativos de Pub/Sub (codificación BINARY)

Para Avro y Protobuf, el esquema se obtiene del registro de esquemas de Pub/Sub del tema. El pipe siempre usa la revisión más reciente del esquema del tema; el selector de esquemas en la UI es de solo lectura por diseño.

​

Compresión

ClickPipes para Pub/Sub detecta y descomprime automáticamente los mensajes comprimidos. El cliente de Pub/Sub entrega bytes sin procesar; ClickPipes se encarga de la descompresión sin necesidad de ninguna configuración.

Se admiten los siguientes códecs de compresión:

• gzip
• zstd
• lz4
• snappy (formato con tramas)

La compresión se detecta automáticamente mediante los bytes mágicos de cada mensaje. Si no se encuentra ninguna firma de compresión conocida, el mensaje se considera sin comprimir. El tipo de compresión detectado también se muestra durante la inferencia de esquema, para que la vista previa de los datos de muestra en la UI muestre correctamente la payload descomprimida.

La detección automática es segura para formatos basados en texto como JSON, ya que los caracteres ASCII imprimibles nunca coincidirán con los bytes mágicos de compresión. La payload descomprimida está limitada a 64 MB.

​

Tipos de datos admitidos

​

Compatibilidad con tipos estándar

Actualmente, ClickPipes admite los siguientes tipos de datos de ClickHouse:

• Tipos numéricos básicos: [U]Int8/16/32/64, Float32/64 y BFloat16
• Tipos enteros de gran tamaño: [U]Int128/256
• Tipos decimales
• Booleano
• String
• FixedString
• Date, Date32
• DateTime, DateTime64 (solo zonas horarias UTC)
• Enum8/Enum16
• UUID
• IPv4
• IPv6
• Todos los tipos LowCardinality de ClickHouse
• Map con claves y valores que usan cualquiera de los tipos anteriores (incluidos Nullable)
• Tuple y Array con elementos que usan cualquiera de los tipos anteriores (incluidos Nullable; solo un nivel de profundidad)
• Tipos SimpleAggregateFunction (para destinos AggregatingMergeTree o SummingMergeTree)

​

Compatibilidad con el tipo Variant

Puede especificar manualmente un tipo Variant (como Variant(String, Int64, DateTime)) para cualquier campo JSON en el flujo de datos de origen. Debido a la forma en que ClickPipes determina qué subtipo de variante corresponde usar, solo puede utilizarse un tipo entero o de fecha y hora en la definición de Variant; por ejemplo, Variant(Int64, UInt32) no es compatible.

​

Compatibilidad con el tipo JSON

Los campos JSON que siempre sean un objeto JSON pueden asignarse a una columna de destino de tipo JSON. Tendrá que cambiar manualmente la columna de destino al tipo JSON deseado, incluidas las rutas fijas o excluidas.

​

Columnas virtuales de Pub/Sub

Las siguientes columnas virtuales son compatibles con los temas de Pub/Sub. Al crear una nueva tabla de destino, se pueden añadir columnas virtuales mediante el botón Add Column.

Name	Description	Recommended Data Type
_message_id	ID del mensaje de Pub/Sub asignado por el broker	String
_publish_time	marca temporal de publicación de Pub/Sub (precisión de milisegundos, UTC)	DateTime64(3)
_ordering_key	clave de ordenación de Pub/Sub (cadena vacía cuando no se establece ninguna clave en el mensaje)	String
_attributes	atributos del mensaje de Pub/Sub definidos por el usuario	Map(String, String)
_raw_message	payload completo del mensaje de Pub/Sub (deshabilitado de forma predeterminada)	String

El campo _raw_message puede usarse cuando solo se requiere el payload completo del mensaje de Pub/Sub (por ejemplo, al usar funciones de ClickHouse JsonExtract* para poblar una vista materializada posterior). En esos pipes, eliminar todas las columnas “no virtuales” puede mejorar el rendimiento de ClickPipes.

​

Limitaciones

• DEFAULT no se admite.
• Los mensajes individuales están limitados de forma predeterminada a 8 MB (sin comprimir) al usar el tamaño de réplica más pequeño (XS), y a 16 MB (sin comprimir) con réplicas más grandes. Los mensajes que superen este límite se rechazarán con un error. Si necesita mensajes más grandes, póngase en contacto con el equipo de soporte.
• Los filtros de suscripción de Pub/Sub son inmutables: para cambiar la expresión de filtro, es necesario volver a crear el pipe.
• Los filtros se aplican solo a los atributos del mensaje, no al payload del mensaje.

​

Rendimiento

​

Procesamiento por lotes

ClickPipes inserta datos en ClickHouse en lotes. Esto evita crear demasiadas partes en la base de datos, lo que puede provocar problemas de rendimiento en el clúster.

Los lotes se insertan cuando se cumple uno de los siguientes criterios:

• El tamaño del lote alcanza el máximo (100,000 filas o 32MB por cada 1GB de memoria de réplica)
• El lote ha permanecido abierto durante el tiempo máximo permitido (5 segundos)

​

Latencia

La latencia (definida como el tiempo que transcurre entre la publicación de un mensaje de Pub/Sub y el momento en que está disponible en ClickHouse) dependerá de varios factores (latencia del publicador, latencia de la red, tamaño/formato del mensaje). El procesamiento por lotes descrito en la sección anterior también afectará a la latencia. Siempre recomendamos probar su caso de uso específico para entender qué latencia puede esperar.

Si tiene requisitos específicos de baja latencia, contáctenos.

​

Claves de ordenación

Pub/Sub garantiza que los mensajes que comparten la misma clave de ordenación se entregan en el orden de publicación a un único suscriptor. ClickPipes habilita la ordenación en sus suscripciones gestionadas de forma predeterminada: cuando los mensajes incluyen claves de ordenación, los suscriptores los reciben en orden; cuando no las incluyen, el comportamiento no cambia.

Si su productor publica todos los mensajes con un número reducido de claves de ordenación (o con una sola clave), Pub/Sub dirigirá esos mensajes a un número reducido de suscriptores, lo que puede limitar el rendimiento horizontal. Recomendamos omitir las claves de ordenación cuando no sea necesario mantener el orden, o bien usar una clave de ordenación de alta cardinalidad.

​

Escalado

ClickPipes para Pub/Sub está diseñado para escalar tanto horizontal como verticalmente. Cada pipe utiliza una única suscripción gestionada de Pub/Sub; esto no se puede configurar. De forma predeterminada, un consumidor lee de esa suscripción; puedes aumentar el número de consumidores durante la creación del ClickPipe o en cualquier otro momento en Configuración -> Configuración avanzada -> Escalado. ClickPipes distribuye automáticamente los mensajes de la suscripción entre los consumidores en ejecución; no se requiere coordinación adicional.

ClickPipes ofrece alta disponibilidad con una arquitectura distribuida entre zonas de disponibilidad; para ello, es necesario escalar a al menos dos consumidores.

Independientemente del número de consumidores en ejecución, la tolerancia a fallos está garantizada por diseño. Si un consumidor o la infraestructura subyacente fallan, ClickPipes reiniciará automáticamente el consumidor y seguirá procesando mensajes.

​

Semántica de entrega

ClickPipes para Pub/Sub ofrece entrega al menos una vez. Un mensaje de Pub/Sub solo se confirma después de que la fila correspondiente se haya insertado en ClickHouse (o se haya escrito en la tabla de errores en el caso de registros malformados); todos los mensajes se confirman una vez procesados, incluidos los registros incorrectos enviados a la tabla de errores, para evitar una reentrega infinita. Si una réplica falla después de la inserción pero antes de que la confirmación llegue a Pub/Sub, el mensaje se volverá a entregar una vez vencido el ack deadline y se insertará de nuevo, por lo que los consumidores posteriores deben tolerar duplicados. Si necesita exactly-once semantics, deduplique aguas abajo usando la columna virtual _message_id (cada ID de mensaje de Pub/Sub es único dentro de un tema).

​

Autenticación

ClickPipes para Pub/Sub se autentica en GCP mediante una clave JSON de una cuenta de servicio. Debe cargar el archivo de clave al crear el pipe; ClickPipes lo cifra en reposo y lo utiliza en tiempo de ejecución para consumir mensajes y gestionar el ciclo de vida de la suscripción gestionada.

Para ver la lista exacta de permisos de IAM necesarios y una definición recomendada de rol personalizado, consulte la guía de permisos de IAM de Pub/Sub.