catálogo de Lakekeeper - ClickHouse Documentation

La integración con el catálogo de Lakekeeper funciona únicamente con tablas Iceberg. Esta integración admite tanto AWS S3 como otros proveedores de almacenamiento en la nube.

ClickHouse admite la integración con varios catálogos (Unity, Glue, REST, Polaris, etc.). Esta guía le mostrará los pasos para consultar sus datos con ClickHouse y el catálogo Lakekeeper. Lakekeeper es una implementación de código abierto de un catálogo REST para Apache Iceberg que ofrece:

Implementación nativa en Rust para alto rendimiento y fiabilidad
Compatibilidad de la API REST con la especificación de REST catalog de Iceberg
Integración con almacenamiento en la nube mediante almacenamiento compatible con S3

Como esta funcionalidad es experimental, deberá habilitarla con: SET allow_experimental_database_iceberg = 1;

Configuración para el desarrollo local

Para el desarrollo y las pruebas en local, puede usar una configuración de Lakekeeper en contenedores. Este enfoque es ideal para el aprendizaje, la creación de prototipos y los entornos de desarrollo.

Requisitos previos

Docker and Docker Compose: Asegúrate de que Docker esté instalado y en ejecución
Configuración de ejemplo: Puedes usar la configuración de Lakekeeper con docker-compose

Configuración del catálogo local de Lakekeeper

Puede usar la configuración oficial de Lakekeeper con Docker Compose, que proporciona un entorno completo con Lakekeeper, un backend de metadatos de PostgreSQL y MinIO como almacenamiento de objetos. Paso 1: Cree una carpeta nueva en la que ejecutar el ejemplo y, a continuación, cree un archivo docker-compose.yml con la siguiente configuración:

version: '3.8'

services:
  lakekeeper:
    image: quay.io/lakekeeper/catalog:latest
    environment:
      - LAKEKEEPER__PG_ENCRYPTION_KEY=This-is-NOT-Secure!
      - LAKEKEEPER__PG_DATABASE_URL_READ=postgresql://postgres:postgres@db:5432/postgres
      - LAKEKEEPER__PG_DATABASE_URL_WRITE=postgresql://postgres:postgres@db:5432/postgres
      - RUST_LOG=info
    command: ["serve"]
    healthcheck:
      test: ["CMD", "/home/nonroot/lakekeeper", "healthcheck"]
      interval: 1s
      timeout: 10s
      retries: 10
      start_period: 30s
    depends_on:
      migrate:
        condition: service_completed_successfully
      db:
        condition: service_healthy
      minio:
        condition: service_healthy
    ports:
      - 8181:8181
    networks:
      - iceberg_net

  migrate:
    image: quay.io/lakekeeper/catalog:latest-main
    environment:
      - LAKEKEEPER__PG_ENCRYPTION_KEY=This-is-NOT-Secure!
      - LAKEKEEPER__PG_DATABASE_URL_READ=postgresql://postgres:postgres@db:5432/postgres
      - LAKEKEEPER__PG_DATABASE_URL_WRITE=postgresql://postgres:postgres@db:5432/postgres
      - RUST_LOG=info
    restart: "no"
    command: ["migrate"]
    depends_on:
      db:
        condition: service_healthy
    networks:
      - iceberg_net

  bootstrap:
    image: curlimages/curl
    depends_on:
      lakekeeper:
        condition: service_healthy
    restart: "no"
    command:
      - -w
      - "%{http_code}"
      - "-X"
      - "POST"
      - "-v"
      - "http://lakekeeper:8181/management/v1/bootstrap"
      - "-H"
      - "Content-Type: application/json"
      - "--data"
      - '{"accept-terms-of-use": true}'
      - "-o"
      - "/dev/null"
    networks:
      - iceberg_net

  initialwarehouse:
    image: curlimages/curl
    depends_on:
      lakekeeper:
        condition: service_healthy
      bootstrap:
        condition: service_completed_successfully
    restart: "no"
    command:
      - -w
      - "%{http_code}"
      - "-X"
      - "POST"
      - "-v"
      - "http://lakekeeper:8181/management/v1/warehouse"
      - "-H"
      - "Content-Type: application/json"
      - "--data"
      - '{"warehouse-name": "demo", "project-id": "00000000-0000-0000-0000-000000000000", "storage-profile": {"type": "s3", "bucket": "warehouse-rest", "key-prefix": "", "assume-role-arn": null, "endpoint": "http://minio:9000", "region": "local-01", "path-style-access": true, "flavor": "minio", "sts-enabled": true}, "storage-credential": {"type": "s3", "credential-type": "access-key", "aws-access-key-id": "minio", "aws-secret-access-key": "ClickHouse_Minio_P@ssw0rd"}}'
      - "-o"
      - "/dev/null"
    networks:
      - iceberg_net

  db:
    image: bitnami/postgresql:16.3.0
    environment:
      - POSTGRESQL_USERNAME=postgres
      - POSTGRESQL_PASSWORD=postgres
      - POSTGRESQL_DATABASE=postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -p 5432 -d postgres"]
      interval: 2s
      timeout: 10s
      retries: 5
      start_period: 10s
    volumes:
      - postgres_data:/bitnami/postgresql
    networks:
      - iceberg_net

  minio:
    image: bitnami/minio:2025.4.22
    environment:
      - MINIO_ROOT_USER=minio
      - MINIO_ROOT_PASSWORD=ClickHouse_Minio_P@ssw0rd
      - MINIO_API_PORT_NUMBER=9000
      - MINIO_CONSOLE_PORT_NUMBER=9001
      - MINIO_SCHEME=http
      - MINIO_DEFAULT_BUCKETS=warehouse-rest
    networks: 
      iceberg_net:
        aliases:
          - warehouse-rest.minio
    ports:
      - "9002:9000"
      - "9003:9001"
    healthcheck:
      test: ["CMD", "mc", "ls", "local", "|", "grep", "warehouse-rest"]
      interval: 2s
      timeout: 10s
      retries: 3
      start_period: 15s
    volumes:
      - minio_data:/bitnami/minio/data

  clickhouse:
    image: clickhouse/clickhouse-server:head
    container_name: lakekeeper-clickhouse
    user: '0:0'  # Garantiza permisos de root
    ports:
      - "8123:8123"
      - "9000:9000"
    volumes:
      - clickhouse_data:/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=
    depends_on:
      lakekeeper:
        condition: service_healthy
      minio:
        condition: service_healthy

volumes:
  postgres_data:
  minio_data:
  clickhouse_data:

networks:
  iceberg_net:
    driver: bridge

Paso 2: Ejecute el siguiente comando para iniciar los servicios:

docker compose up -d

Paso 3: Espera a que todos los servicios estén listos. Puedes consultar los logs:

docker-compose logs -f

La configuración de Lakekeeper requiere que primero se carguen datos de ejemplo en las tablas Iceberg. Asegúrate de que el entorno haya creado y rellenado las tablas antes de intentar consultarlas a través de 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 catálogo local de Lakekeeper

Conéctese al contenedor de ClickHouse:

docker exec -it lakekeeper-clickhouse clickhouse-client

A continuación, cree la conexión de la base de datos al catálogo de Lakekeeper:

SET allow_experimental_database_iceberg = 1;

CREATE DATABASE demo
ENGINE = DataLakeCatalog('http://lakekeeper:8181/catalog', 'minio', 'ClickHouse_Minio_P@ssw0rd')
SETTINGS catalog_type = 'rest', storage_endpoint = 'http://minio:9002/warehouse-rest', warehouse = 'demo'

Consultar tablas del catálogo de Lakekeeper con ClickHouse

Ahora que la conexión ya está configurada, puedes empezar a realizar consultas mediante el catálogo de Lakekeeper. 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:

El entorno aún no ha creado las tablas de ejemplo
El servicio de catálogo de Lakekeeper no se ha inicializado por completo
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 comillas invertidasLas comillas invertidas son necesarias 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:9002/warehouse-rest/warehouse/default/taxis/', 'minio', '[HIDDEN]') │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

Cargar datos de tu lago de datos en ClickHouse

Si necesitas cargar datos del catálogo de Lakekeeper en ClickHouse, empieza por crear una tabla local de 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 de la tabla de tu catálogo de Lakekeeper con un INSERT INTO SELECT:

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

​Configuración para el desarrollo local

​Requisitos previos

​Configuración del catálogo local de Lakekeeper

​Conectarse al catálogo local de Lakekeeper

​Consultar tablas del catálogo de Lakekeeper con ClickHouse

​Cargar datos de tu lago de datos en ClickHouse

Configuración para el desarrollo local

Requisitos previos

Configuración del catálogo local de Lakekeeper

Conectarse al catálogo local de Lakekeeper

Consultar tablas del catálogo de Lakekeeper con ClickHouse

Cargar datos de tu lago de datos en ClickHouse