Conectar Apify a ClickHouse - ClickHouse Documentation

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.

Conceptos clave

Concepto de Apify	Qué es
Actor	Un programa serverless en la nube que se ejecuta en la plataforma de Apify. Hay miles de Actors listos para usar disponibles en la Apify Store.
Dataset	El resultado de la ejecución de un Actor. Una colección de objetos JSON similar a una tabla, que puede recuperarse como JSON, CSV, XML u otros formatos mediante la Apify API.
Webhook	Una llamada HTTP basada en eventos que se activa cuando la ejecución de un Actor finaliza correctamente, falla o alcanza otros eventos de su ciclo de vida. Usa webhooks para automatizar el pipeline de Apify a ClickHouse.

Guía de configuración

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.

Detalles de conexión HTTPS de ClickHouse Cloud

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

Apify también ofrece un cliente de Python. Si prefieres Python, instala apify-client con pip y usa clickhouse-connect para ClickHouse.

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();

Para datasets grandes, pagina los resultados con los parámetros limit y offset del endpoint List dataset items. También puedes pasar clean=true para recuperar solo elementos no vacíos y deduplicados.

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:

En la Apify Console, ve a tu Actor y abre la pestaña Integrations.
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.
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.

Buenas prácticas

Recuperación de datos de Apify

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.

Carga en ClickHouse

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.

Rendimiento

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.

Seguridad

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.

​Conceptos clave

​Guía de configuración

​Buenas prácticas

​Recuperación de datos de Apify

​Carga en ClickHouse

​Rendimiento

​Seguridad

​Recursos relacionados

Conceptos clave

Guía de configuración

Buenas prácticas

Recuperación de datos de Apify

Carga en ClickHouse

Rendimiento

Seguridad

Recursos relacionados