Catálogo de Nessie - ClickHouse Documentation

La integración con el catálogo de Nessie solo funciona 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.). En esta guía se explican los pasos para consultar sus datos con ClickHouse y el catálogo Nessie. Nessie es un catálogo transaccional de código abierto para lagos de datos que ofrece:

Control de versiones de datos inspirado en Git con ramas y commits
Transacciones entre tablas y garantías de visibilidad
Compatibilidad con la API REST y con la especificación de REST catalog de Iceberg
Un enfoque de lago de datos abierto compatible con Hive, Spark, Dremio, Trino y más
Implementación lista para producción en Docker o Kubernetes

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

Configuración local para desarrollo

Para el desarrollo y las pruebas en local, puedes usar una implementación de Nessie en contenedores. Este enfoque es ideal para aprender, crear prototipos y trabajar en entornos de desarrollo.

Requisitos previos

Docker y Docker Compose: Asegúrate de que Docker esté instalado y en funcionamiento
Configuración de ejemplo: Puedes usar la configuración oficial de Docker Compose de Nessie

Configuración de un catálogo de Nessie local

Puedes usar la configuración oficial de Docker Compose de Nessie, que proporciona un entorno completo con Nessie, un almacén de versiones en memoria y MinIO para el almacenamiento de objetos. Paso 1: Crea una carpeta nueva para ejecutar el ejemplo y, a continuación, crea un archivo docker-compose.yml con la siguiente configuración:

version: '3.8'

services:
  nessie:
    image: ghcr.io/projectnessie/nessie:latest
    ports:
      - "19120:19120"
    environment:
      - nessie.version.store.type=IN_MEMORY
      - nessie.catalog.default-warehouse=warehouse
      - nessie.catalog.warehouses.warehouse.location=s3://my-bucket/
      - nessie.catalog.service.s3.default-options.endpoint=http://minio:9000/
      - nessie.catalog.service.s3.default-options.access-key=urn:nessie-secret:quarkus:nessie.catalog.secrets.access-key
      - nessie.catalog.service.s3.default-options.path-style-access=true
      - nessie.catalog.service.s3.default-options.auth-type=STATIC
      - nessie.catalog.secrets.access-key.name=admin
      - nessie.catalog.secrets.access-key.secret=password
      - nessie.catalog.service.s3.default-options.region=us-east-1
      - nessie.server.authentication.enabled=false
    depends_on:
      minio:
        condition: service_healthy
    networks:
      - iceberg_net

  minio:
    image: quay.io/minio/minio
    ports:
      - "9002:9000"
      - "9003:9001"
    environment:
      - MINIO_ROOT_USER=admin
      - MINIO_ROOT_PASSWORD=password
      - MINIO_REGION=us-east-1
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 5s
      timeout: 10s
      retries: 5
      start_period: 30s
    entrypoint: >
      /bin/sh -c "
      minio server /data --console-address ':9001' &
      sleep 10;
      mc alias set myminio http://localhost:9000 admin password;
      mc mb myminio/my-bucket --ignore-existing;
      tail -f /dev/null"
    networks:
      - iceberg_net

  clickhouse:
    image: clickhouse/clickhouse-server:head
    container_name: nessie-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 conjunto de datos
    networks:
      - iceberg_net
    environment:
      - CLICKHOUSE_DB=default
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_DO_NOT_CHOWN=1
      - CLICKHOUSE_PASSWORD=
    depends_on:
      nessie:
        condition: service_started
      minio:
        condition: service_healthy

volumes:
  clickhouse_data:

networks:
  iceberg_net:
    driver: bridge

Paso 2: Ejecuta 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 Nessie usa un almacén de versiones en memoria y requiere que primero se carguen datos de ejemplo en las tablas Iceberg. Asegúrate de que el entorno haya creado y llenado las tablas antes de intentar consultarlas a través de ClickHouse.

Conectarse al catálogo de Nessie local

Conéctese a su contenedor de ClickHouse:

docker exec -it nessie-clickhouse clickhouse-client

A continuación, cree la conexión de base de datos con el catálogo de Nessie:

SET allow_experimental_database_iceberg = 1;

CREATE DATABASE demo
ENGINE = DataLakeCatalog('http://nessie:19120/iceberg', 'admin', 'password')
SETTINGS catalog_type = 'rest', storage_endpoint = 'http://minio:9002/my-bucket', warehouse = 'warehouse'

Consultar tablas del catálogo de Nessie con ClickHouse

Ahora que la conexión está configurada, puede empezar a hacer consultas a través del catálogo de Nessie. Por ejemplo:

USE demo;

SHOW TABLES;

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

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

Si no ve ninguna tabla, por lo general significa lo siguiente:

El entorno todavía no ha creado las tablas de ejemplo
El servicio del catálogo de Nessie no está completamente inicializado
El proceso de carga de los datos de ejemplo aún no ha finalizado

Puede revisar los logs de Nessie para ver la actividad del catálogo:

docker-compose logs nessie

Para consultar una tabla (si está disponible):

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

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

Se requieren backticksLos backticks son necesarios 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://localhost:9002/my-bucket/default/taxis/', 'admin', '[HIDDEN]')      │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

Cargar datos desde tu lago de datos a ClickHouse

Si necesitas cargar datos del catálogo de Nessie en 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);

Luego, carga los datos de la tabla de tu catálogo de Nessie mediante un INSERT INTO SELECT:

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

​Configuración local para desarrollo

​Requisitos previos

​Configuración de un catálogo de Nessie local

​Conectarse al catálogo de Nessie local

​Consultar tablas del catálogo de Nessie con ClickHouse

​Cargar datos desde tu lago de datos a ClickHouse

Configuración local para desarrollo

Requisitos previos

Configuración de un catálogo de Nessie local

Conectarse al catálogo de Nessie local

Consultar tablas del catálogo de Nessie con ClickHouse

Cargar datos desde tu lago de datos a ClickHouse