catálogo REST

En esta guía, le mostraremos cómo consultar sus datos con ClickHouse y el catálogo REST.

La integración con el REST Catalog funciona solo con tablas Iceberg. Esta integración es compatible tanto con AWS S3 como con otros proveedores de almacenamiento en la nube.

ClickHouse admite la integración con múltiples catálogos (Unity, Glue, REST, Polaris, etc.). En esta guía se explica cómo consultar sus datos con ClickHouse y la especificación REST Catalog.

El REST Catalog es una especificación de API estandarizada para catálogos Iceberg, compatible con varias plataformas, entre ellas:

• Entornos de desarrollo local (con configuraciones de docker-compose)
• Servicios gestionados como Tabular.io
• Implementaciones self-hosted de REST Catalog

Como esta funcionalidad está en beta, deberá habilitarla con: SET allow_database_iceberg = 1;

​

Configuración para desarrollo local

Para el desarrollo y las pruebas locales, puedes usar una configuración de catálogo REST basada en contenedores. Este enfoque es ideal para el aprendizaje, la creación de prototipos y los entornos de desarrollo.

​

Requisitos previos

1. Docker and Docker Compose: Asegúrate de que Docker esté instalado y en funcionamiento
2. Configuración de ejemplo: Puedes usar varias configuraciones de docker-compose (consulta las imágenes de Docker alternativas más abajo)

​

Configuración de un catálogo REST local

Puede usar varias implementaciones de catálogo REST en contenedores, como Databricks docker-spark-iceberg, que proporciona un entorno completo de Spark + Iceberg + catálogo REST con docker-compose, por lo que resulta ideal para probar integraciones con Iceberg.

Paso 1: Cree una carpeta nueva en la que ejecutar el ejemplo y, a continuación, cree un archivo docker-compose.yml con la configuración de Databricks docker-spark-iceberg.

Paso 2: A continuación, cree un archivo docker-compose.override.yml y añada en él la siguiente configuración del contenedor de ClickHouse:

version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:25.5.6
    container_name: clickhouse
    user: '0:0'  # Garantiza permisos de root
    ports:
      - "8123:8123"
      - "9002:9000"
    volumes:
      - ./clickhouse:/var/lib/clickhouse
      - ./clickhouse/data_import:/var/lib/clickhouse/data_import  # Montar carpeta del dataset
    networks:
      - iceberg_net
    environment:
      - CLICKHOUSE_DB=default
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_DO_NOT_CHOWN=1
      - CLICKHOUSE_PASSWORD=

Paso 3: Ejecuta el siguiente comando para iniciar los servicios:

docker compose up

Paso 4: Espera a que todos los servicios estén listos. Puedes revisar los logs:

docker-compose logs -f

La configuración del catálogo REST requiere que primero se carguen datos de ejemplo en las tablas Iceberg. Asegúrate de que el entorno de Spark haya creado y rellenado las tablas antes de intentar consultarlas desde ClickHouse. La disponibilidad de las tablas depende de la configuración específica de docker-compose y de los scripts de carga de datos de ejemplo.

​

Conectarse al REST Catalog local

Conéctese al contenedor de ClickHouse:

docker exec -it clickhouse clickhouse-client

Luego, cree la conexión de base de datos al catálogo REST:

SET allow_database_iceberg = 1;

CREATE DATABASE demo
ENGINE = DataLakeCatalog('http://rest:8181/v1', 'admin', 'password')
SETTINGS 
    catalog_type = 'rest', 
    storage_endpoint = 'http://minio:9000/lakehouse', 
    warehouse = 'demo'

​

Consultar tablas del catálogo REST con ClickHouse

Ahora que la conexión está lista, puedes empezar a hacer consultas a través del catálogo REST. Por ejemplo:

USE demo;

SHOW TABLES;

Si su configuración incluye datos de ejemplo (como el conjunto de datos de taxis), debería ver tablas como:

┌─name──────────┐
│ default.taxis │
└───────────────┘

Si no ves ninguna tabla, normalmente significa lo siguiente:

1. El entorno de Spark aún no ha creado las tablas de ejemplo
2. El servicio de catálogo REST todavía no se ha inicializado por completo
3. El proceso de carga de los datos de ejemplo aún no ha finalizado

Puedes revisar los logs de Spark para ver el progreso de creación de las tablas:

docker-compose logs spark

Para consultar una tabla (si está disponible):

SELECT count(*) FROM `default.taxis`;

┌─count()─┐
│ 2171187 │
└─────────┘

Se requieren backticks

Los backticks son obligatorios porque ClickHouse no admite más de un espacio de nombres.

Para inspeccionar el DDL de la tabla:

SHOW CREATE TABLE `default.taxis`;

┌─statement─────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE demo.`default.taxis`                                                             │
│ (                                                                                             │
│     `VendorID` Nullable(Int64),                                                               │
│     `tpep_pickup_datetime` Nullable(DateTime64(6)),                                           │
│     `tpep_dropoff_datetime` Nullable(DateTime64(6)),                                          │
│     `passenger_count` Nullable(Float64),                                                      │
│     `trip_distance` Nullable(Float64),                                                        │
│     `RatecodeID` Nullable(Float64),                                                           │
│     `store_and_fwd_flag` Nullable(String),                                                    │
│     `PULocationID` Nullable(Int64),                                                           │
│     `DOLocationID` Nullable(Int64),                                                           │
│     `payment_type` Nullable(Int64),                                                           │
│     `fare_amount` Nullable(Float64),                                                          │
│     `extra` Nullable(Float64),                                                                │
│     `mta_tax` Nullable(Float64),                                                              │
│     `tip_amount` Nullable(Float64),                                                           │
│     `tolls_amount` Nullable(Float64),                                                         │
│     `improvement_surcharge` Nullable(Float64),                                                │
│     `total_amount` Nullable(Float64),                                                         │
│     `congestion_surcharge` Nullable(Float64),                                                 │
│     `airport_fee` Nullable(Float64)                                                           │
│ )                                                                                             │
│ ENGINE = Iceberg('http://minio:9000/lakehouse/warehouse/default/taxis/', 'admin', '[HIDDEN]') │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

​

Cargar datos desde tu lago de datos a ClickHouse

Si necesitas cargar datos desde el catálogo REST a ClickHouse, empieza por crear una tabla local en ClickHouse:

CREATE TABLE taxis
(
    `VendorID` Int64,
    `tpep_pickup_datetime` DateTime64(6),
    `tpep_dropoff_datetime` DateTime64(6),
    `passenger_count` Float64,
    `trip_distance` Float64,
    `RatecodeID` Float64,
    `store_and_fwd_flag` String,
    `PULocationID` Int64,
    `DOLocationID` Int64,
    `payment_type` Int64,
    `fare_amount` Float64,
    `extra` Float64,
    `mta_tax` Float64,
    `tip_amount` Float64,
    `tolls_amount` Float64,
    `improvement_surcharge` Float64,
    `total_amount` Float64,
    `congestion_surcharge` Float64,
    `airport_fee` Float64
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(tpep_pickup_datetime)
ORDER BY (VendorID, tpep_pickup_datetime, PULocationID, DOLocationID);

A continuación, carga los datos desde la tabla de tu catálogo REST mediante un INSERT INTO SELECT:

INSERT INTO taxis 
SELECT * FROM demo.`default.taxis`;