DataLakeCatalog

O mecanismo de banco de dados DataLakeCatalog permite conectar o ClickHouse a catálogos de dados externos e consultar dados em formatos abertos de tabela sem a necessidade de duplicação de dados. Isso transforma o ClickHouse em um poderoso motor de consulta que se integra perfeitamente à sua infraestrutura de lago de dados existente.

Catálogos compatíveis

O mecanismo DataLakeCatalog oferece suporte aos seguintes catálogos de dados:

AWS Glue Catalog - Para tabelas Iceberg em ambientes AWS
Databricks Unity Catalog - Para tabelas Delta Lake e Iceberg
Hive Metastore - Catálogo tradicional do ecossistema Hadoop
REST Catalogs - Qualquer catálogo compatível com a especificação REST do Iceberg

Criando um banco de dados

Para usar o mecanismo DataLakeCatalog, você precisará habilitar as configurações relevantes abaixo:

SET allow_database_iceberg = 1;
SET allow_database_unity_catalog = 1;
SET allow_database_glue_catalog = 1;
SET allow_experimental_database_hms_catalog = 1;
SET allow_experimental_database_paimon_rest_catalog = 1;

Bancos de dados com o mecanismo DataLakeCatalog podem ser criados usando a sintaxe a seguir:

CREATE DATABASE database_name
ENGINE = DataLakeCatalog(catalog_endpoint[, user, password])
SETTINGS
catalog_type,
[...]

As configurações a seguir são suportadas:

Configuração	Descrição
`catalog_type`	Tipo de catálogo: `glue`, `unity` (Delta, ou Delta e Iceberg com `use_unity_catalog_v2`), `rest` (Iceberg), `hive`, `onelake` (Iceberg), `delta_sharing` (Iceberg, espaços de nomes simples), `horizon` (Snowflake Horizon Iceberg REST)
`warehouse`	Nome do warehouse/banco de dados a ser usado no catálogo.
`catalog_credential`	Credencial de autenticação para o catálogo (por exemplo, chave de API ou token)
`use_unity_catalog_v2`	Para `catalog_type = 'unity'`: use a nova implementação, que oferece suporte a tabelas Delta Lake e Iceberg. Padrão: `false`. Defina-a em `CREATE` ou altere-a para um banco de dados existente com `ALTER DATABASE ... MODIFY SETTING`.
`auth_header`	Cabeçalho HTTP personalizado para autenticação com o serviço de catálogo
`auth_scope`	Escopo OAuth2 para autenticação (se estiver usando OAuth)
`storage_endpoint`	URL do endpoint para o armazenamento subjacente
`oauth_server_uri`	URI do servidor de autorização OAuth2 para autenticação
`vended_credentials`	Booleano que indica se devem ser usadas credenciais fornecidas pelo catálogo (compatível com AWS S3 e Azure ADLS Gen2)
`aws_access_key_id`	ID da chave de acesso da AWS para acesso ao S3/Glue (se não estiver usando credenciais fornecidas)
`aws_secret_access_key`	Chave secreta de acesso da AWS para acesso ao S3/Glue (se não estiver usando credenciais fornecidas)
`aws_role_arn`	ARN da IAM role a ser assumida para acesso ao AWS/Glue. Quando definida, o ClickHouse usa AWS STS `AssumeRole` com credenciais base de `aws_access_key_id` e `aws_secret_access_key` quando ambas são fornecidas, ou da cadeia de credenciais padrão da AWS, caso contrário (a role deve confiar na identidade sob a qual o servidor é executado).
`aws_role_session_name`	Nome da sessão usado para a chamada AWS STS `AssumeRole`. Opcional; o padrão é `ClickHouseSession`.
`aws_external_id`	ID externo passado para AWS STS `AssumeRole`, correspondendo à condição `sts:ExternalId` na trust policy da role. Use isso quando a role pertencer a terceiros, como o ClickHouse Cloud.
`region`	Região da AWS para o serviço (por exemplo, `us-east-1`)
`dlf_access_key_id`	ID da chave de acesso para o DLF
`dlf_access_key_secret`	Chave secreta de acesso para o DLF
`force_add_bucket`	Ao construir URLs de armazenamento de objetos a partir da localização da tabela fornecida pelo catálogo e de `storage_endpoint`, adicione o nome do bucket/container no início, mesmo que o endpoint já o contenha. Padrão: `false`. Defina como `true` para catálogos que retornam paths sem o bucket e exigem que ele seja adicionado na etapa de construção da URL (paths no estilo Polaris).

Exemplos

Consulte as seções abaixo para ver exemplos de uso do mecanismo DataLakeCatalog:

Unity Catalog
Unity Catalog com tabelas Delta Lake e Iceberg Com use_unity_catalog_v2 = 1, o catálogo unity oferece suporte a tabelas Delta Lake e Iceberg, detectando o formato de cada tabela.

CREATE DATABASE database_name
ENGINE = DataLakeCatalog('https://<workspace>.cloud.databricks.com/api/2.1/unity-catalog')
SETTINGS
    catalog_type = 'unity',
    use_unity_catalog_v2 = 1,
    warehouse = 'my_catalog',
    catalog_credential = '<client_id>:<client_secret>';
SHOW TABLES FROM database_name;
SELECT count() FROM database_name.`schema_name.table_name`;

catalog_credential aceita um principal de serviço OAuth no formato <client_id>:<client_secret>, um token de acesso pessoal (dapi...) ou um token OAuth obtido previamente.

Glue Catalog
OneLake Catalog Pode ser usado ao habilitar allow_database_iceberg.

CREATE DATABASE database_name
ENGINE = DataLakeCatalog(catalog_endpoint)
SETTINGS
    catalog_type = 'onelake',
    warehouse = warehouse,
    onelake_tenant_id = tenant_id,
    oauth_server_uri = server_uri,
    auth_scope = auth_scope,
    onelake_client_id = client_id,
    onelake_client_secret = client_secret;
SHOW TABLES IN database_name;
SELECT count() from database_name.table_name;

Para autenticar sem compartilhar um segredo do cliente, defina onelake_bearer_token como um Bearer token obtido previamente (com escopo para https://storage.azure.com) em vez de onelake_client_id/onelake_client_secret. O ClickHouse não renova o token, portanto o banco de dados deve ser recriado após sua expiração.

Referência de SQL

Tipos de dados

Motores

Funções

Formatos

Configurações

Tabelas de sistema

Lagos de dados

Catálogos compatíveis

Criando um banco de dados

Exemplos

​Catálogos compatíveis

​Criando um banco de dados

​Exemplos

Catálogos compatíveis

Criando um banco de dados

Exemplos