Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

DataLakeCatalog

View as MarkdownEdit this pageReport an issueSet up docs MCP

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_experimental_database_iceberg = 1;
SET allow_experimental_database_unity_catalog = 1;
SET allow_experimental_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), 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)
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
  • Glue Catalog
  • OneLake Catalog Pode ser usado ao habilitar allow_experimental_database_iceberg ou 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.

Navigation