Conectar Apify a ClickHouse

Apify es una plataforma de web scraping y automatización. En ella puedes crear, ejecutar y escalar programas serverless en la nube llamados Actors. Los Actors extraen datos de sitios web, rastrean la web, procesan datos o automatizan flujos de trabajo. Cada ejecución de un Actor genera una salida estructurada almacenada en Datasets (colecciones de objetos JSON).

Carga en ClickHouse los datos extraídos o procesados para análisis, monitoreo o pipelines de enriquecimiento.

Recopila los detalles de conexión de ClickHouse

Para conectarse a ClickHouse con HTTP(S), necesita esta información:

Parámetro(s)	Descripción
HOST and PORT	Normalmente, el puerto es 8443 cuando se usa TLS o 8123 cuando no se usa TLS.
DATABASE NAME	De forma predeterminada, existe una base de datos llamada default; use el nombre de la base de datos a la que desea conectarse.
USERNAME and PASSWORD	De forma predeterminada, el nombre de usuario es default. Use el nombre de usuario adecuado para su caso de uso.

Los detalles de su servicio de ClickHouse Cloud están disponibles en la consola de ClickHouse Cloud. Seleccione un servicio y haga clic en Connect:

Elija HTTPS. Los detalles de conexión se muestran en un comando curl de ejemplo.

Si usa ClickHouse autogestionado, los detalles de conexión los establece su administrador de ClickHouse.

Requisitos previos de Apify

También necesitarás lo siguiente:

• Una cuenta de Apify (hay un nivel gratuito disponible).
• Un token de API de Apify, que encontrarás en Settings > Integrations en la Apify Console.
• Node.js 18+ instalado localmente (para los ejemplos en JavaScript).

Instala las dependencias

Instala el cliente de JavaScript de Apify y el cliente de JavaScript de ClickHouse:

npm install apify-client @clickhouse/client

Crea una tabla de destino en ClickHouse

Crea una tabla para almacenar los datos extraídos. El esquema depende del Actor que uses. Este ejemplo usa MergeTree para un Actor de scraping de productos:

CREATE TABLE apify_products
(
    url        String,
    title      String,
    price      Float64,
    currency   String,
    scraped_at DateTime DEFAULT now()
)
ENGINE = MergeTree()
ORDER BY (scraped_at, url);

Obtén el dataset de Apify y cárgalo en ClickHouse

El siguiente script obtiene los resultados de una ejecución de un Actor de Apify y los inserta en ClickHouse:

import { ApifyClient } from 'apify-client';
import { createClient } from '@clickhouse/client';

// Inicializar clientes
const apify = new ApifyClient({ token: 'YOUR_APIFY_API_TOKEN' });
const clickhouse = createClient({
    url: 'https://YOUR_CLICKHOUSE_HOST:8443',
    username: 'default',
    password: 'YOUR_CLICKHOUSE_PASSWORD',
    database: 'default',
});

// Obtener elementos del dataset de la última ejecución de un Actor
const run = await apify.actor('YOUR_ACTOR_ID').call();
const { items } = await apify.dataset(run.defaultDatasetId).listItems();

console.log(`Fetched ${items.length} items from Apify dataset.`);

// Insertar en ClickHouse
await clickhouse.insert({
    table: 'apify_products',
    values: items,
    format: 'JSONEachRow',
});

console.log(`Inserted ${items.length} rows into ClickHouse.`);
await clickhouse.close();

Automatiza con webhooks

En lugar de ejecutar el script manualmente, automatiza el pipeline para que los datos se carguen en ClickHouse cada vez que termine un Actor:

1. En la Apify Console, ve a tu Actor y abre la pestaña Integrations.
2. Añade un webhook nuevo con:
   • Event type: ACTOR.RUN.SUCCEEDED
   • Action: un HTTP POST a tu endpoint de carga, o activa otro Actor que gestione la inserción en ClickHouse.
3. El payload del webhook incluye defaultDatasetId, que puedes usar para obtener los resultados de la ejecución.

Consulta la documentación de webhooks de Apify para ver los detalles del payload y las opciones de configuración.

Otra alternativa es usar Apify Schedules para ejecutar Actors con una programación tipo cron, combinado con webhooks para el paso de carga.

Utiliza la biblioteca cliente de Apify (apify-client para JavaScript o Python) en lugar de hacer solicitudes HTTP directas. Se encarga de la paginación, los reintentos y la autenticación por ti. Para datasets grandes, pagina los resultados con los parámetros limit y offset del endpoint List dataset items.

Utiliza el formato JSONEachRow al insertar datos en ClickHouse. Se corresponde directamente con la salida JSON de Apify, sin necesidad de realizar ninguna transformación.

Haz que el esquema de la tabla de ClickHouse coincida con los campos de salida del Actor. Consulta el esquema de salida del Actor en su página de Apify Store o en la pestaña Dataset después de una ejecución.

Para inserciones de alto rendimiento desde el cliente de JavaScript, siga los Consejos para optimizar el rendimiento. Agrupe las filas en lotes de inserción más grandes en lugar de insertarlas una por una, y considere las inserciones asíncronas cuando la agrupación en lotes del lado del cliente no sea viable.

Los ejemplos de esta página usan el usuario y la base de datos default para simplificar. En producción, cree un usuario específico con los privilegios mínimos necesarios para insertar datos en la tabla de destino y almacene las credenciales de forma segura (por ejemplo, en variables de entorno o en un gestor de secretos, en lugar de subirlas al código fuente). Consulte Gestión de acceso a Cloud para obtener más información.

• Documentación de la plataforma Apify
• Referencia de la API de Apify
• Cliente de JavaScript de Apify
• Cliente de Python de Apify
• Apify Store (Actors listos para usar)
• Descripción general de las integraciones de Apify
• Cliente de JavaScript de ClickHouse