Primeros pasos con lagos de datos

La forma más rápida de empezar —especialmente para consultas ad hoc o cuando no uses un catálogo— es con la función de tabla icebergS3(). Apúntala a una tabla Iceberg en S3 y haz la consulta de inmediato, sin necesidad de configuración.

Inspecciona el esquema:

DESCRIBE icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

Ejecuta una consulta:

SELECT
    url,
    count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

ClickHouse lee los metadatos de Iceberg directamente desde S3 e infiere el esquema automáticamente. El mismo enfoque también funciona con deltaLake(), hudi() y paimon().

Más información: Consultar directamente formatos de tabla abiertos abarca los cuatro formatos, las variantes de cluster para lecturas distribuidas y las opciones de backend de almacenamiento (S3, Azure, HDFS, local).

Cuando no use un catálogo pero vaya a consultar la misma ruta repetidamente, cree una tabla con el motor de tabla Iceberg para no tener que indicar la ruta cada vez. Los datos permanecen en S3 — no se duplica ningún dato:

CREATE TABLE hits_iceberg
    ENGINE = IcebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

Ahora consúltala como cualquier otra tabla de ClickHouse:

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

El motor de tabla admite caché de datos, caché de metadatos, evolución del esquema y viaje en el tiempo. Consulta la guía Consulta directa para obtener más información sobre las características del motor de tabla y la matriz de compatibilidad para ver una comparación completa de características.

Si su organización utiliza un catálogo de datos, esta es la ruta de integración que recomendamos. Los catálogos centralizan los metadatos de las tablas y su detección; en lugar de administrar una definición de tabla para cada ruta de almacenamiento, conéctese una sola vez con el motor de base de datos DataLakeCatalog. Cada tabla del catálogo aparece como una tabla de ClickHouse, incluidas las tablas añadidas upstream después de crear la conexión.

A continuación se muestra un ejemplo de conexión a AWS Glue:

CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = '<your-region>',
    aws_access_key_id = '<your-access-key>',
    aws_secret_access_key = '<your-secret-key>'

Cada tipo de catálogo requiere su propia configuración de conexión; consulte las guías sobre catálogos para ver la lista completa de catálogos compatibles y sus opciones de configuración.

Explore las tablas y realice consultas:

SHOW TABLES FROM my_lake;

SELECT count(*) FROM my_lake.`<database>.<table>`

Más información: Conexión a un catálogo de datos muestra una configuración completa de Unity Catalog con ejemplos de Delta e Iceberg.

Independientemente del método que haya usado antes —función de tabla, motor de tabla o DataLakeCatalog—, el mismo ClickHouse SQL funciona en todos los casos. En producción con un catálogo, consulte a través de la base de datos DataLakeCatalog; los demás ejemplos siguen siendo útiles para pruebas rápidas y para acceso basado en rutas:

-- Table function
SELECT url, count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- Table engine
SELECT url, count() AS cnt
FROM hits_iceberg
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- Catalog
SELECT url, count() AS cnt
FROM my_lake.`<database>.<table>`
GROUP BY url ORDER BY cnt DESC LIMIT 5

La sintaxis de la consulta es idéntica; solo cambia la cláusula FROM. Todas las funciones de ClickHouse SQL, los JOIN y las agregaciones funcionan de la misma manera independientemente de la fuente de datos.

Consultar Iceberg directamente es práctico, pero el rendimiento está limitado por el ancho de banda de la red y la organización de los archivos. Para cargas de trabajo analíticas, cargue los datos en una tabla nativa MergeTree.

Primero, ejecute una consulta filtrada sobre la tabla Iceberg para obtener una referencia:

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Esta consulta recorre el conjunto de datos completo en S3, ya que Iceberg no tiene en cuenta el filtro counterid; es de esperar que tarde varios segundos.

Ahora crea una tabla MergeTree y carga los datos:

CREATE TABLE hits_clickhouse
(
    url String,
    eventtime DateTime,
    counterid UInt32
)
ENGINE = MergeTree()
ORDER BY (counterid, eventtime);

INSERT INTO hits_clickhouse
SELECT url, eventtime, counterid
FROM hits_iceberg

Vuelva a ejecutar la misma consulta en la tabla MergeTree:

SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

Como counterid es la primera columna de la clave ORDER BY, el índice primario disperso de ClickHouse salta directamente a los gránulos relevantes y solo lee las filas de counterid = 38, en lugar de escanear los 100 millones de filas. El resultado es un aumento drástico de la velocidad.

La guía aceleración de analítica va un paso más allá con tipos LowCardinality, índices de texto completo y claves de ordenación optimizadas, y muestra una mejora de ~40x en un conjunto de datos de 283 millones de filas.

Más información: Aceleración de analítica con MergeTree abarca la optimización del esquema, la indexación de texto completo y una comparación completa del rendimiento antes y después.

ClickHouse también puede escribir datos de vuelta en tablas de Iceberg, lo que permite flujos de trabajo de ETL inverso: publicar resultados agregados o subconjuntos para que otras herramientas (Spark, Trino, DuckDB, etc.) los consuman.

Cree una tabla de Iceberg para la salida:

CREATE TABLE output_iceberg
(
    url String,
    cnt UInt64
)
ENGINE = IcebergS3('https://your-bucket.s3.amazonaws.com/output/', 'access_key', 'secret_key')

Escriba resultados agregados:

SET allow_experimental_insert_into_iceberg = 1;

INSERT INTO output_iceberg
SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
GROUP BY url
ORDER BY cnt DESC

La tabla Iceberg resultante se puede leer con cualquier motor compatible con Iceberg.

Más información: Escribir datos en formatos de tabla abiertos explica cómo escribir datos sin procesar y resultados agregados con el conjunto de datos UK Price Paid, incluidas las consideraciones de esquema al mapear tipos de ClickHouse a Iceberg.