Unity Catalog - ClickHouse Documentation

O ClickHouse oferece suporte à integração com vários catálogos (Unity, Glue, Polaris etc.). Este guia mostrará as etapas para consultar os dados gerenciados pelo Databricks usando o ClickHouse e o Unity Catalog. O Databricks oferece suporte a vários formatos de dados para seu lakehouse. Com o ClickHouse, você pode consultar tabelas do Unity Catalog tanto no formato Delta quanto Iceberg.

Como este recurso é experimental, você precisará habilitá-lo usando: SET allow_experimental_database_unity_catalog = 1;

Configurando o Unity Catalog no Databricks

Para permitir que o ClickHouse interaja com o Unity Catalog, você precisa garantir que o Unity Catalog esteja configurado para permitir a interação com um leitor externo. Isso pode ser feito seguindo o guia “Enable external data access to Unity Catalog”. Depois que o catálogo estiver configurado, você deverá gerar credenciais para o ClickHouse. Dois métodos diferentes podem ser usados, dependendo do modo de interação com o Unity:

Para clientes Iceberg, use autenticação como service principal.
Para clientes Delta, use um Token de Acesso Pessoal (PAT).

Permissões obrigatórias do token PAT

Ao usar um PAT para acesso somente leitura, o token precisa ter permissões que permitam ao ClickHouse listar e ler os metadados do Unity Catalog. Certifique-se de que o PAT tenha pelo menos o privilégio EXTERNAL USE SCHEMA, além da permissão SELECT na tabela, USE CATALOG no catálogo pai e USE SCHEMA no schema pai.

Criando uma conexão entre Unity Catalog e ClickHouse

Com o Unity Catalog configurado e a autenticação em vigor, estabeleça uma conexão entre o ClickHouse e o Unity Catalog.

Ler Delta

CREATE DATABASE unity
ENGINE = DataLakeCatalog('https://<workspace-id>.cloud.databricks.com/api/2.1/unity-catalog')
SETTINGS warehouse = 'CATALOG_NAME', catalog_credential = '<PAT>', catalog_type = 'unity'

Ler tabelas Iceberg

Para acessar tabelas Iceberg gerenciadas:

CREATE DATABASE unity
ENGINE = DataLakeCatalog('https://<workspace-id>.cloud.databricks.com/api/2.1/unity-catalog/iceberg-rest')
SETTINGS catalog_type = 'rest', catalog_credential = '<client-id>:<client-secret>', warehouse = 'workspace', 
oauth_server_uri = 'https://<workspace-id>.cloud.databricks.com/oidc/v1/token', auth_scope = 'all-apis,sql'

Consultando tabelas do Unity Catalog com o ClickHouse

Agora que a conexão está estabelecida, você já pode começar a fazer consultas por meio do Unity Catalog. Por exemplo:

USE unity;

SHOW TABLES;

┌─name───────────────────────────────────────────────┐
│ clickbench.delta_hits                              │
│ demo.fake_user                                     │
│ information_schema.catalog_privileges              │
│ information_schema.catalog_tags                    │
│ information_schema.catalogs                        │
│ information_schema.check_constraints               │
│ information_schema.column_masks                    │
│ information_schema.column_tags                     │
│ information_schema.columns                         │
│ information_schema.constraint_column_usage         │
│ information_schema.constraint_table_usage          │
│ information_schema.information_schema_catalog_name │
│ information_schema.key_column_usage                │
│ information_schema.parameters                      │
│ information_schema.referential_constraints         │
│ information_schema.routine_columns                 │
│ information_schema.routine_privileges              │
│ information_schema.routines                        │
│ information_schema.row_filters                     │
│ information_schema.schema_privileges               │
│ information_schema.schema_tags                     │
│ information_schema.schemata                        │
│ information_schema.table_constraints               │
│ information_schema.table_privileges                │
│ information_schema.table_tags                      │
│ information_schema.tables                          │
│ information_schema.views                           │
│ information_schema.volume_privileges               │
│ information_schema.volume_tags                     │
│ information_schema.volumes                         │
│ uniform.delta_hits                                 │
└────────────────────────────────────────────────────┘

SHOW TABLES

┌─name───────────────┐
│ uniform.delta_hits │
└────────────────────┘

Para consultar uma tabela:

SELECT count(*) FROM `uniform.delta_hits`

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 `uniform.delta_hits`

CREATE TABLE unity_uniform.`uniform.delta_hits`
(
    `WatchID` Int64,
    `JavaEnable` Int32,
    `Title` String,
    `GoodEvent` Int32,
    `EventTime` DateTime64(6, 'UTC'),
    `EventDate` Date,
    `CounterID` Int32,
    `ClientIP` Int32,
    ...
    `FromTag` String,
    `HasGCLID` Int32,
    `RefererHash` Int64,
    `URLHash` Int64,
    `CLID` Int32
)
ENGINE = Iceberg('s3://<path>);

Carregando dados do seu lago de dados para o ClickHouse

Se você precisar carregar dados do Databricks para o ClickHouse, comece criando uma tabela local no ClickHouse:

CREATE TABLE hits
(
    `WatchID` Int64,
    `JavaEnable` Int32,
    `Title` String,
    `GoodEvent` Int32,
    `EventTime` DateTime64(6, 'UTC'),
    `EventDate` Date,
    `CounterID` Int32,
    `ClientIP` Int32,
    ...
    `FromTag` String,
    `HasGCLID` Int32,
    `RefererHash` Int64,
    `URLHash` Int64,
    `CLID` Int32
)
PRIMARY KEY (CounterID, EventDate, UserID, EventTime, WatchID);

Em seguida, carregue os dados da sua tabela no Unity Catalog por meio de um INSERT INTO SELECT:

INSERT INTO hits SELECT * FROM unity_uniform.`uniform.delta_hits`;

​Configurando o Unity Catalog no Databricks

​Permissões obrigatórias do token PAT

​Criando uma conexão entre Unity Catalog e ClickHouse

​Ler Delta

​Ler tabelas Iceberg

​Consultando tabelas do Unity Catalog com o ClickHouse

​Carregando dados do seu lago de dados para o ClickHouse

Configurando o Unity Catalog no Databricks

Permissões obrigatórias do token PAT

Criando uma conexão entre Unity Catalog e ClickHouse

Ler Delta

Ler tabelas Iceberg

Consultando tabelas do Unity Catalog com o ClickHouse

Carregando dados do seu lago de dados para o ClickHouse