catálogo REST - ClickHouse Documentation

A integração com o catálogo REST funciona apenas com tabelas Iceberg. Esta integração oferece suporte tanto ao S3 da AWS quanto a outros provedores de armazenamento em nuvem.

O ClickHouse oferece suporte à integração com vários catálogos (Unity, Glue, REST, Polaris etc.). Este guia mostrará o passo a passo para consultar seus dados usando o ClickHouse e a especificação catálogo REST. O catálogo REST é uma especificação padronizada de API para catálogos Iceberg, compatível com várias plataformas, incluindo:

Ambientes locais de desenvolvimento (usando configurações com docker-compose)
Serviços gerenciados como o Tabular.io
Implementações self-hosted de catálogo REST

Como este recurso está em beta, você precisará habilitá-lo com: SET allow_database_iceberg = 1;

Configuração de desenvolvimento local

Para desenvolvimento e testes locais, você pode usar uma configuração de catálogo REST em contêiner. Essa abordagem é ideal para aprendizado, prototipagem e ambientes de desenvolvimento.

Pré-requisitos

Docker e Docker Compose: Certifique-se de que o Docker esteja instalado e em execução
Configuração de exemplo: Você pode usar diferentes configurações do docker-compose (veja as imagens Docker alternativas abaixo)

Configurando o catálogo REST local

Você pode usar várias implementações de catálogo REST em contêiner, como o Databricks docker-spark-iceberg, que fornece um ambiente completo com Spark + Iceberg + catálogo REST via docker-compose, tornando-o ideal para testar integrações com o Iceberg. Etapa 1: Crie uma nova pasta para executar o exemplo e, em seguida, crie um arquivo docker-compose.yml com a configuração do Databricks docker-spark-iceberg. Etapa 2: Em seguida, crie um arquivo docker-compose.override.yml e adicione a ele a seguinte configuração de contêiner do ClickHouse:

version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:25.5.6
    container_name: clickhouse
    user: '0:0'  # Garante permissões de root
    ports:
      - "8123:8123"
      - "9002:9000"
    volumes:
      - ./clickhouse:/var/lib/clickhouse
      - ./clickhouse/data_import:/var/lib/clickhouse/data_import  # Monta a pasta do dataset
    networks:
      - iceberg_net
    environment:
      - CLICKHOUSE_DB=default
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_DO_NOT_CHOWN=1
      - CLICKHOUSE_PASSWORD=

Etapa 3: Execute o comando a seguir para iniciar os serviços:

docker compose up

Etapa 4: Aguarde até que todos os serviços estejam prontos. Você pode verificar os logs:

docker-compose logs -f

A configuração do catálogo REST exige que os dados de exemplo sejam carregados primeiro nas tabelas Iceberg. Certifique-se de que o ambiente do Spark tenha criado e populado as tabelas antes de tentar fazer consultas nelas por meio do ClickHouse. A disponibilidade das tabelas depende da configuração específica do docker-compose e dos scripts de carregamento dos dados de exemplo.

Conectando-se ao Catálogo REST local

Conecte-se ao seu contêiner do ClickHouse:

docker exec -it clickhouse clickhouse-client

Em seguida, crie a conexão do banco de dados com o 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'

Consultando tabelas do catálogo REST com o ClickHouse

Agora que a conexão está estabelecida, você já pode começar a fazer consultas pelo catálogo REST. Por exemplo:

USE demo;

SHOW TABLES;

Se a sua configuração incluir dados de exemplo (como o dataset de táxi), você deverá ver tabelas como:

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

Se você não vir nenhuma tabela, isso geralmente significa que:

O ambiente Spark ainda não criou as tabelas de exemplo
O serviço de catálogo REST ainda não foi totalmente inicializado
O processo de carregamento dos dados de exemplo ainda não foi concluído

Você pode verificar os logs do Spark para acompanhar o progresso da criação das tabelas:

docker-compose logs spark

Para consultar uma tabela (se estiver disponível):

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

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

Backticks obrigatóriosOs backticks são obrigatórios porque o ClickHouse não oferece suporte a mais de um espaço de nomes.

Para inspecionar o DDL da tabela:

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]') │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

Carregando dados do seu lago de dados para o ClickHouse

Se você precisar carregar dados do catálogo REST para o ClickHouse, comece criando uma tabela local no 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);

Em seguida, carregue os dados da tabela do seu catálogo REST usando um INSERT INTO SELECT:

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

​Configuração de desenvolvimento local

​Pré-requisitos

​Configurando o catálogo REST local

​Conectando-se ao Catálogo REST local

​Consultando tabelas do catálogo REST com o ClickHouse

​Carregando dados do seu lago de dados para o ClickHouse

Configuração de desenvolvimento local

Pré-requisitos

Configurando o catálogo REST local

Conectando-se ao Catálogo REST local

Consultando tabelas do catálogo REST com o ClickHouse

Carregando dados do seu lago de dados para o ClickHouse