Unity Catalog

Neste guia, mostramos como consultar seus dados em buckets do S3 usando ClickHouse e o Unity Catalog.

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órios

Os 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`;