Uso de la interfaz HTTP de ClickHouse en Azure Data Factory

La función de tabla azureBlobStorage es una forma rápida y práctica de ingestar datos desde Azure Blob Storage en ClickHouse. Sin embargo, no siempre es la opción adecuada por las siguientes razones:

Es posible que sus datos no estén almacenados en Azure Blob Storage; por ejemplo, podrían estar en Azure SQL Database, Microsoft SQL Server o Cosmos DB.
Las políticas de seguridad pueden impedir por completo el acceso externo a Blob Storage; por ejemplo, si la cuenta de almacenamiento está restringida y no tiene ningún endpoint público.

En estos casos, puede usar Azure Data Factory junto con la interfaz HTTP de ClickHouse para enviar datos desde los servicios de Azure a ClickHouse. Este método invierte el flujo: en lugar de que ClickHouse extraiga los datos de Azure, Azure Data Factory envía los datos a ClickHouse. Este enfoque normalmente requiere que su instancia de ClickHouse sea accesible desde internet.

Es posible evitar exponer su instancia de ClickHouse a internet mediante el Self-hosted Integration Runtime de Azure Data Factory. Esta configuración permite enviar datos a través de una red privada. Sin embargo, esto queda fuera del alcance de este artículo. Puede encontrar más información en la guía oficial: Crear y configurar un entorno de ejecución de integración autohospedado

Convertir ClickHouse en un servicio REST

Azure Data Factory permite enviar datos a sistemas externos a través de HTTP en formato JSON. Podemos usar esta capacidad para insertar datos directamente en ClickHouse mediante la interfaz HTTP de ClickHouse. Puede obtener más información en la documentación de interfaz HTTP de ClickHouse. Para este ejemplo, solo necesitamos especificar la tabla de destino, definir el formato de los datos de entrada como JSON e incluir opciones para permitir un procesamiento más flexible de las marcas de tiempo.

INSERT INTO my_table
SETTINGS 
    date_time_input_format='best_effort',
    input_format_json_read_objects_as_strings=1
FORMAT JSONEachRow

Para enviar esta consulta como parte de una petición HTTP, simplemente pásela como una cadena codificada en URL al parámetro de consulta de su endpoint de ClickHouse:

https://your-clickhouse-url.com?query=INSERT%20INTO%20my_table%20SETTINGS%20date_time_input_format%3D%27best_effort%27%2C%20input_format_json_read_objects_as_strings%3D1%20FORMAT%20JSONEachRow%0A

Azure Data Factory puede gestionar esta codificación automáticamente con su función integrada encodeUriComponent, por lo que no tienes que hacerlo manualmente.

Ahora puedes enviar datos en formato JSON a esta URL. Los datos deben coincidir con la estructura de la tabla de destino. Aquí tienes un ejemplo sencillo con curl, suponiendo una tabla con tres columnas: col_1, col_2 y col_3.

curl \
    -XPOST "https://your-clickhouse-url.com?query=<our_URL_encded_query>" \
    --data '{"col_1":9119,"col_2":50.994,"col_3":"2019-06-01 00:00:00"}'

También puedes enviar un array JSON de objetos o JSON Lines (objetos JSON delimitados por saltos de línea). Azure Data Factory usa el formato de array JSON, que funciona perfectamente con la entrada JSONEachRow de ClickHouse. Como puedes ver, en este paso no necesitas hacer nada especial del lado de ClickHouse. La interfaz HTTP ya ofrece todo lo necesario para actuar como un endpoint de tipo REST; no hace falta ninguna configuración adicional. Ahora que hemos hecho que ClickHouse se comporte como un endpoint REST, es hora de configurar Azure Data Factory para usarlo. En los siguientes pasos, crearemos una instancia de Azure Data Factory, configuraremos un Linked Service para tu instancia de ClickHouse, definiremos un Dataset para el REST sink y crearemos una actividad Copy Data para enviar datos desde Azure a ClickHouse.

Crear una instancia de Azure Data Factory

Esta guía asume que tienes acceso a una cuenta de Microsoft Azure y que ya has configurado una suscripción y un grupo de recursos. Si ya tienes Azure Data Factory configurado, puedes omitir este paso sin problema y pasar al siguiente usando tu servicio existente.

Inicia sesión en el Microsoft Azure Portal y haz clic en Create a resource.
En el panel de categorías de la izquierda, selecciona Analytics y luego haz clic en Data Factory en la lista de servicios populares.
Selecciona tu suscripción y grupo de recursos, introduce un nombre para la nueva instancia de Data Factory, elige la región y deja la versión en V2.
Haz clic en Review + Create y luego en Create para iniciar la implementación.

Una vez que la implementación se haya completado correctamente, podrás empezar a usar tu nueva instancia de Azure Data Factory.

Creación de un nuevo linked service basado en REST

Inicia sesión en el Microsoft Azure Portal y abre tu instancia de Data Factory.
En la página de información general de Data Factory, haz clic en Launch Studio.
En el menú de la izquierda, selecciona Manage, luego ve a Linked services y haz clic en + New para crear un nuevo linked service.
En la barra de búsqueda de New linked service, escribe REST, selecciona REST y haz clic en Continue para crear una instancia del conector REST.
En el panel de configuración del linked service, introduce un nombre para tu nuevo servicio, haz clic en el campo Base URL y luego en Add dynamic content (este enlace solo aparece cuando el campo está seleccionado).
En el panel de contenido dinámico puedes crear una URL parametrizada, lo que te permite definir la consulta más adelante al crear datasets para distintas tablas; esto hace que el linked service se pueda reutilizar.
Haz clic en el ”+” junto al campo de filtro y agrega un nuevo parámetro; asígnale el nombre pQuery, establece el tipo en String y el valor predeterminado en SELECT 1. Haz clic en Save.
En el campo de expresión, introduce lo siguiente y haz clic en OK. Reemplaza your-clickhouse-url.com por la dirección real de tu instancia de ClickHouse.
@{concat('https://your-clickhouse-url.com:8443/?query=', encodeUriComponent(linkedService().pQuery))}
De vuelta en el formulario principal, selecciona basic authentication, introduce el username y la password que usas para conectarte a tu interfaz HTTP de ClickHouse y haz clic en Test connection. Si todo está configurado correctamente, verás un mensaje de éxito.
Haz clic en Create para finalizar la configuración.

Ahora deberías ver en la lista el linked service basado en REST que acabas de registrar.

Creación de un nuevo conjunto de datos para la interfaz HTTP de ClickHouse

Ahora que tenemos un servicio vinculado configurado para la interfaz HTTP de ClickHouse, podemos crear un conjunto de datos que Azure Data Factory usará para enviar datos a ClickHouse. En este ejemplo, insertaremos una pequeña parte de Environmental Sensors Data.

Abra la consola de consultas de ClickHouse que prefiera; puede ser la interfaz web de ClickHouse Cloud, el cliente de CLI o cualquier otra interfaz que use para ejecutar consultas, y cree la tabla de destino:

CREATE TABLE sensors
(
    sensor_id UInt16,
    lat Float32,
    lon Float32,
    timestamp DateTime,
    temperature Float32
)
ENGINE = MergeTree
ORDER BY (timestamp, sensor_id);

En Azure Data Factory Studio, seleccione Author en el panel izquierdo. Pase el cursor sobre el elemento Dataset, haga clic en el icono de tres puntos y elija New dataset.
En la barra de búsqueda, escriba REST, seleccione REST y haga clic en Continue. Introduzca un nombre para su conjunto de datos y seleccione el linked service que creó en el paso anterior. Haga clic en OK para crear el conjunto de datos.
Ahora debería ver el conjunto de datos recién creado en la sección Datasets del panel Factory Resources a la izquierda. Seleccione el conjunto de datos para abrir sus propiedades. Verá el parámetro pQuery que se definió en el servicio vinculado. Haga clic en el campo de texto Value. Después, haga clic en Add dynamic content.

En el panel que se abre, pegue la siguiente consulta:

INSERT INTO sensors
SETTINGS 
    date_time_input_format=''best_effort'', 
    input_format_json_read_objects_as_strings=1 
FORMAT JSONEachRow

Todas las comillas simples ' de la consulta deben sustituirse por dos comillas simples ''. Esto es necesario debido al analizador de expresiones de Azure Data Factory. Si no las escapa, puede que no vea un error de inmediato, pero fallará más adelante cuando intente usar o guardar el conjunto de datos. Por ejemplo, 'best_effort' debe escribirse como ''best_effort''.

Haga clic en OK para guardar la expresión. Haga clic en Test connection. Si todo está configurado correctamente, verá el mensaje Connection successful. Haga clic en Publish all en la parte superior de la página para guardar los cambios.

Configuración de un conjunto de datos de ejemplo

En este ejemplo, no usaremos el Environmental Sensors Dataset completo, sino solo un pequeño subconjunto disponible en Sensors Dataset Sample.

Para que esta guía siga siendo concisa, no detallaremos los pasos exactos para crear el conjunto de datos de origen en Azure Data Factory. Puede cargar los datos de muestra en cualquier servicio de almacenamiento que prefiera, por ejemplo, Azure Blob Storage, Microsoft SQL Server o incluso en otro formato de archivo compatible con Azure Data Factory.

Cargue el conjunto de datos en Azure Blob Storage (u otro servicio de almacenamiento que prefiera). Luego, en Azure Data Factory Studio, vaya al panel Factory Resources. Cree un nuevo conjunto de datos que apunte a los datos cargados. Haga clic en Publish all para guardar los cambios.

Crear una actividad de copia para transferir datos a ClickHouse

Ahora que hemos configurado tanto los datasets de entrada como de salida, podemos crear una actividad de Copy Data para transferir datos de nuestro dataset de ejemplo a la tabla sensors de ClickHouse.

Abra Azure Data Factory Studio y vaya a la pestaña Author. En el panel Factory Resources, pase el cursor sobre Pipeline, haga clic en el icono de tres puntos y seleccione New pipeline.
En el panel Activities, expanda la sección Move and transform y arrastre la actividad Copy data al lienzo.
Seleccione la pestaña Source y elija el dataset de origen que creó anteriormente.
Vaya a la pestaña Sink y seleccione el dataset de ClickHouse creado para la tabla sensors. Establezca Request method en POST. Asegúrese de que HTTP compression type esté configurado como None.

La compresión HTTP no funciona correctamente en la actividad Copy Data de Azure Data Factory. Cuando está habilitada, Azure envía un payload compuesto únicamente por bytes cero — probablemente un error del servicio. Asegúrese de dejar la compresión deshabilitada.

Recomendamos mantener el tamaño de lote predeterminado de 10.000, o incluso aumentarlo más. Para obtener más información, consulte Selecting an Insert Strategy / Batch inserts if synchronous.

Haga clic en Debug en la parte superior del lienzo para ejecutar el pipeline. Tras una breve espera, la actividad se pondrá en cola y se ejecutará. Si todo está configurado correctamente, la tarea debería finalizar con el estado Success.
Una vez completado, haga clic en Publish all para guardar los cambios en el pipeline y el dataset.

​Convertir ClickHouse en un servicio REST

​Crear una instancia de Azure Data Factory

​Creación de un nuevo linked service basado en REST

​Creación de un nuevo conjunto de datos para la interfaz HTTP de ClickHouse

​Configuración de un conjunto de datos de ejemplo

​Crear una actividad de copia para transferir datos a ClickHouse

​Recursos adicionales

Convertir ClickHouse en un servicio REST

Crear una instancia de Azure Data Factory

Creación de un nuevo linked service basado en REST

Creación de un nuevo conjunto de datos para la interfaz HTTP de ClickHouse

Configuración de un conjunto de datos de ejemplo

Crear una actividad de copia para transferir datos a ClickHouse

Recursos adicionales