catálogo SeaweedFS

ClickHouse admite la integración con varios catálogos (Unity, Glue, REST, Polaris, etc.). Esta guía le mostrará cómo consultar sus datos con ClickHouse y el catálogo SeaweedFS.

SeaweedFS es un almacén distribuido de archivos y objetos de código abierto con una puerta de enlace compatible con S3. Sus S3 Table Buckets proporcionan ambas partes de una implementación de Iceberg: el catálogo REST de Iceberg integrado sirve los metadatos de las tablas y el bucket de tablas almacena los datos de las tablas como archivos Parquet a través del mismo endpoint de S3:

• Servicio único: los metadatos del catálogo y los datos Parquet se sirven desde un único proceso, sin una base de datos de metadatos independiente
• Cumplimiento de la especificación de catálogo REST de Iceberg mediante la API REST
• Mantenimiento en el servidor: compactación automática de archivos Parquet y expiración de snapshots, sin un servicio de mantenimiento externo

Para el desarrollo y las pruebas locales, puede ejecutar SeaweedFS y ClickHouse con Docker Compose. Este enfoque es ideal para aprender, crear prototipos y trabajar en entornos de desarrollo.

1. Docker y Docker Compose: asegúrese de que Docker esté instalado y en ejecución
2. Versiones: SeaweedFS 4.42 o posterior; ClickHouse 26.8 o posterior (las versiones desde la 25.8 pueden leer e insertar, pero para crear tablas mediante el catálogo se requiere la 26.8)
3. Python con PyIceberg (opcional): se utiliza a continuación para inicializar datos de muestra

Paso 1: Cree una carpeta nueva para ejecutar el ejemplo y, a continuación, cree un archivo s3config.json con las credenciales de la puerta de enlace de S3 y del catálogo:

{
  "identities": [
    {
      "name": "analyst",
      "credentials": [
        {
          "accessKey": "tutorialkey",
          "secretKey": "tutorialsecret"
        }
      ],
      "actions": ["Admin", "Read", "Write", "List", "Tagging"]
    }
  ]
}

Paso 2: Cree un archivo docker-compose.yml con la siguiente configuración:

services:
  seaweedfs:
    image: chrislusf/seaweedfs:latest
    command: mini -dir=/data -s3.config=/etc/seaweedfs/s3config.json -tableBucket=analytics -admin.port=12646
    ports:
      - "8333:8333"   # S3 endpoint
      - "8181:8181"   # Iceberg REST catalog
    volumes:
      - ./s3config.json:/etc/seaweedfs/s3config.json
      - seaweedfs_data:/data
    networks:
      - iceberg_net

  clickhouse:
    image: clickhouse/clickhouse-server:latest
    container_name: seaweedfs-clickhouse
    ports:
      - "8123:8123"
      - "9000:9000"
    depends_on:
      - seaweedfs
    networks:
      - iceberg_net

volumes:
  seaweedfs_data:

networks:
  iceberg_net:
    driver: bridge

El comando mini inicia toda la pila de SeaweedFS en un único contenedor. El indicador -tableBucket=analytics crea de antemano un bucket de S3 Tables llamado analytics, que sirve como warehouse de Iceberg. -admin.port=12646 mantiene el puerto gRPC de administración que SeaweedFS deriva a partir de él por debajo del rango de puertos efímeros de Linux, donde, de otro modo, una conexión de inicio podría reclamarlo primero.

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

docker compose up -d

El catálogo está inicialmente vacío. Cree una tabla y añada algunas filas con PyIceberg (pip install pyiceberg pyarrow):

import pyarrow as pa

from pyiceberg.catalog.rest import RestCatalog

catalog = RestCatalog(
    "seaweedfs",
    uri="http://localhost:8181",
    warehouse="s3://analytics",
    credential="tutorialkey:tutorialsecret",
    **{
        "s3.endpoint": "http://localhost:8333",
        "s3.access-key-id": "tutorialkey",
        "s3.secret-access-key": "tutorialsecret",
        "s3.region": "us-east-1",
        "s3.path-style-access": "true",
    },
)

rows = pa.table({
    "id": pa.array([1, 2, 3, 4, 5, 6], pa.int64()),
    "region": ["NA", "EU", "EU", "APAC", "NA", "EU"],
    "amount": pa.array([12.5, 40.0, 7.25, 99.9, 3.5, 61.0], pa.float64()),
})

catalog.create_namespace("sales")
table = catalog.create_table("sales.orders", schema=rows.schema)
table.append(rows)

Conéctese a su contenedor de ClickHouse:

docker exec -it seaweedfs-clickhouse clickhouse-client

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

SET allow_experimental_database_iceberg = 1;

CREATE DATABASE lake
ENGINE = DataLakeCatalog('http://seaweedfs:8181/v1', 'tutorialkey', 'tutorialsecret')
SETTINGS catalog_type = 'rest',
    warehouse = 's3://analytics',
    storage_endpoint = 'http://seaweedfs:8333/analytics',
    catalog_credential = 'tutorialkey:tutorialsecret',
    oauth_server_uri = 'http://seaweedfs:8181/v1/oauth/tokens'

Los argumentos del motor contienen las credenciales de S3 que ClickHouse utiliza para leer los datos de la tabla, mientras que catalog_credential y oauth_server_uri autentican en el propio catálogo mediante el flujo OAuth2 de credenciales de cliente. SeaweedFS acepta la misma clave de acceso y clave secreta para ambos.

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

USE lake;

SHOW TABLES;

┌─name─────────┐
│ sales.orders │
└──────────────┘

Para consultar una tabla:

SELECT region, sum(amount) AS total
FROM `sales.orders`
GROUP BY region
ORDER BY total DESC;

┌─region─┬──total─┐
│ EU     │ 108.25 │
│ APAC   │   99.9 │
│ NA     │     16 │
└────────┴────────┘

También puede crear tablas en el catálogo de SeaweedFS y escribir directamente en ellas desde ClickHouse:

SET allow_experimental_database_iceberg = 1;
SET allow_experimental_insert_into_iceberg = 1;
SET write_full_path_in_iceberg_metadata = 1;

CREATE TABLE lake.`sales.returns` (id Int64, reason String)
ENGINE = IcebergS3('http://seaweedfs:8333/analytics/sales/returns/', 'tutorialkey', 'tutorialsecret');

INSERT INTO lake.`sales.returns` VALUES (1, 'damaged'), (2, 'wrong size');

SELECT * FROM lake.`sales.returns` ORDER BY id;

┌─id─┬─reason─────┐
│  1 │ damaged    │
│  2 │ wrong size │
└────┴────────────┘

La cláusula del motor IcebergS3 especifica la ruta de almacenamiento de la nueva tabla, y write_full_path_in_iceberg_metadata hace que ClickHouse registre la ubicación completa de la tabla en el catálogo.

Cuando ClickHouse confirma una inserción, el catálogo de SeaweedFS corrige los metadatos que el writer experimental todavía no genera: completa los ID de campo que faltan en los manifests, reescribe como ubicaciones absolutas las rutas de archivo relativas al bucket y asigna a la tabla una correspondencia de nombres predeterminada. Los readers estrictos, como PyIceberg y Spark, pueden entonces leer las filas escritas por ClickHouse. Esto requiere SeaweedFS 4.42 o una versión posterior.

Si necesita cargar datos del catálogo de SeaweedFS en ClickHouse, primero cree una tabla local de ClickHouse:

CREATE TABLE default.orders
(
    `id` Int64,
    `region` String,
    `amount` Float64
)
ENGINE = MergeTree()
ORDER BY (region, id);

A continuación, cargue los datos de la tabla de catálogo de SeaweedFS mediante un INSERT INTO SELECT:

INSERT INTO default.orders
SELECT * FROM lake.`sales.orders`;