Catálogo Snowflake Horizon

O ClickHouse pode se conectar ao Snowflake Horizon Catalog por meio da API REST do Iceberg exposta pelo Horizon (com tecnologia do Apache Polaris). Isso permite ler e gravar tabelas Iceberg gerenciadas pelo Snowflake no ClickHouse usando o mecanismo de banco de dados DataLakeCatalog com catalog_type = 'horizon'. O Horizon é relacionado ao Snowflake Open Catalog / Polaris auto-hospedado, mas não é o mesmo:

	Open Catalog / Polaris (`catalog_type = 'rest'`)	Horizon (`catalog_type = 'horizon'`)
Endpoint	URI do Open Catalog ou do Polaris auto-hospedado	`https://<org>-<account>.snowflakecomputing.com/polaris/api/catalog`
Warehouse	Nome do catálogo Polaris / warehouse	Nome do banco de dados do Snowflake (geralmente em letras maiúsculas)
Escopo de autenticação	`PRINCIPAL_ROLE:ALL` (típico)	`session:role:<ROLE>`
Credencial	`client_id:client_secret`	PAT ou JWT de par de chaves como `catalog_credential` (OAuth client_secret; sem divisão em ’:’), ou `auth_header` do tipo bearer

Como este recurso está em beta, habilite-o com: SET allow_experimental_database_iceberg = 1; (ou SET allow_database_iceberg = 1;, dependendo da versão do ClickHouse).

Pré-requisitos

Uma conta Snowflake com tabelas Iceberg gerenciadas pela Snowflake
Endpoint REST do Horizon Iceberg: https://<organization>-<account>.snowflakecomputing.com/polaris/api/catalog
Uma função do Snowflake com privilégios nas tabelas Iceberg (e privilégios de gravação se você for executar INSERT)
Autenticação por um dos seguintes métodos:
- Token de acesso programático (PAT)
- JWT de par de chaves trocado por um token de acesso
- Token de acesso OAuth externo (como auth_header do tipo bearer)
Armazenamento de objetos acessível pelo ClickHouse (recomendam-se credenciais fornecidas)
ClickHouse com suporte ao DataLakeCatalog Iceberg

Criar uma conexão

Opção A: token de acesso programático (recomendado)

SET allow_experimental_database_iceberg = 1;

CREATE DATABASE horizon_catalog
ENGINE = DataLakeCatalog('https://<org>-<account>.snowflakecomputing.com/polaris/api/catalog')
SETTINGS
    catalog_type = 'horizon',
    warehouse = 'ICEBERG_TEST_DB',
    catalog_credential = '<PAT>',
    auth_scope = 'session:role:DATA_ENGINEER',
    oauth_server_uri = 'https://<org>-<account>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens',
    vended_credentials = 1;

warehouse deve ser o nome do banco de dados no Snowflake (não de um warehouse virtual do Snowflake). Identificadores do Snowflake sem aspas são escritos em maiúsculas.

Opção B: Token de acesso Bearer obtido previamente

CREATE DATABASE horizon_catalog
ENGINE = DataLakeCatalog('https://<org>-<account>.snowflakecomputing.com/polaris/api/catalog')
SETTINGS
    catalog_type = 'horizon',
    warehouse = 'ICEBERG_TEST_DB',
    auth_header = 'Authorization: Bearer <ACCESS_TOKEN>',
    vended_credentials = 1;

Consultar tabelas Iceberg

USE horizon_catalog;
SHOW TABLES;

SELECT count(*) FROM `PUBLIC.test_table`;
SHOW CREATE TABLE `PUBLIC.test_table`;

O espaço de nomes (schema) e a tabela geralmente são referenciados como `SCHEMA.table`, a menos que os espaços de nomes experimentais para tabelas estejam habilitados.

Caminho de gravação

Com uma função que tenha INSERT/UPDATE/DELETE (e CREATE ICEBERG TABLE ao criar tabelas), o ClickHouse pode gravar usando o mesmo catálogo:

-- Insert into an existing Snowflake-managed Iceberg table
INSERT INTO horizon_catalog.`PUBLIC.test_table`
SELECT
    number AS id,
    concat('name_', toString(number)) AS name
FROM numbers(100);

-- Create a new Iceberg table in the Horizon catalog (requires CREATE ICEBERG TABLE)
CREATE TABLE horizon_catalog.`PUBLIC.clickhouse_written`
(
    id Int64,
    name String
)
ENGINE = Iceberg;

A sintaxe exata de CREATE TABLE depende do suporte a escrita do ClickHouse Iceberg / DataLakeCatalog para catálogos REST na versão em uso; falhas de privilégio no Snowflake são exibidas como erros HTTP do catálogo.

Carregamento no MergeTree

CREATE TABLE my_clickhouse_table
(
    id Int64,
    name String
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO my_clickhouse_table
SELECT * FROM horizon_catalog.`PUBLIC.test_table`;

ClickHouse guides

Use case guides

Pré-requisitos

Criar uma conexão

Opção A: token de acesso programático (recomendado)

Opção B: Token de acesso Bearer obtido previamente

Consultar tabelas Iceberg

Caminho de gravação

Carregamento no MergeTree

​Pré-requisitos

​Criar uma conexão

​Opção A: token de acesso programático (recomendado)

​Opção B: Token de acesso Bearer obtido previamente

​Consultar tabelas Iceberg

​Caminho de gravação

​Carregamento no MergeTree

Pré-requisitos

Criar uma conexão

Opção A: token de acesso programático (recomendado)

Opção B: Token de acesso Bearer obtido previamente

Consultar tabelas Iceberg

Caminho de gravação

Carregamento no MergeTree