DataLakeCatalog

El motor de base de datos DataLakeCatalog le permite conectar ClickHouse a catálogos de datos externos y consultar datos en formatos de tabla abiertos sin necesidad de duplicarlos. Esto transforma a ClickHouse en un potente motor de consultas que se integra perfectamente con la infraestructura existente de su lago de datos.

Catálogos compatibles

El motor DataLakeCatalog es compatible con los siguientes catálogos de datos:

AWS Glue Catalog - Para tablas Iceberg en entornos de AWS
Databricks Unity Catalog - Para tablas Delta Lake e Iceberg
Hive Metastore - Catálogo tradicional del ecosistema Hadoop
Catálogos REST - Cualquier catálogo compatible con la especificación REST de Iceberg

Crear una base de datos

Deberá habilitar la configuración correspondiente que se indica a continuación para usar el motor DataLakeCatalog:

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;

Las bases de datos con el motor DataLakeCatalog pueden crearse con la siguiente sintaxis:

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

Se admiten los siguientes ajustes:

Configuración	Descripción
`catalog_type`	Tipo de catálogo: `glue`, `unity` (Delta, o Delta e Iceberg con `use_unity_catalog_v2`), `rest` (Iceberg), `hive`, `onelake` (Iceberg), `delta_sharing` (Iceberg, espacios de nombres planos), `horizon` (Snowflake Horizon Iceberg REST)
`warehouse`	Nombre del almacén/base de datos que se usará en el catálogo.
`catalog_credential`	Credencial de autenticación para el catálogo (p. ej., API key o token)
`use_unity_catalog_v2`	Para `catalog_type = 'unity'`: se usa la nueva implementación, compatible tanto con tablas Delta Lake como con tablas Iceberg. Valor predeterminado: `false`. Establézcalo en `CREATE` o cámbielo en una base de datos existente con `ALTER DATABASE ... MODIFY SETTING`.
`auth_header`	HTTP header personalizado para la autenticación con el servicio de catálogo
`auth_scope`	Scope de OAuth2 para la autenticación (si se usa OAuth)
`storage_endpoint`	URL del endpoint del almacenamiento subyacente
`oauth_server_uri`	URI del servidor de autorización de OAuth2 para la autenticación
`vended_credentials`	Valor booleano que indica si se deben usar las credenciales proporcionadas por el catálogo (admite AWS S3 y Azure ADLS Gen2)
`aws_access_key_id`	ID de la clave de acceso de AWS para acceder a S3/Glue (si no se usan credenciales proporcionadas)
`aws_secret_access_key`	Clave de acceso secreta de AWS para acceder a S3/Glue (si no se usan credenciales proporcionadas)
`aws_role_arn`	ARN del rol de IAM que se debe asumir para el acceso a AWS/Glue. Cuando se establece, ClickHouse usa AWS STS `AssumeRole` con las credenciales base de `aws_access_key_id` y `aws_secret_access_key` cuando se proporcionan ambas, o con la cadena de credenciales predeterminada de AWS de lo contrario (el rol debe confiar en la identidad con la que se ejecuta el servidor).
`aws_role_session_name`	Nombre de la sesión usado para la llamada AWS STS `AssumeRole`. Opcional; el valor predeterminado es `ClickHouseSession`.
`aws_external_id`	ID externo que se pasa a AWS STS `AssumeRole`, coincidiendo con la condición `sts:ExternalId` de la política de confianza del rol. Úselo cuando el rol pertenezca a un tercero, como ClickHouse Cloud.
`region`	Región de AWS para el servicio (p. ej., `us-east-1`)
`dlf_access_key_id`	ID de la clave de acceso para acceder a DLF
`dlf_access_key_secret`	Clave de acceso secreta para acceder a DLF
`force_add_bucket`	Al construir las URL del almacenamiento de objetos a partir de la ubicación de la tabla proporcionada por el catálogo y `storage_endpoint`, anteponga el nombre del bucket/contenedor aunque el endpoint ya lo contenga. Valor predeterminado: `false`. Establézcallo en `true` para los catálogos que devuelven rutas sin el bucket y requieren que se agregue durante el paso de construcción de la URL (rutas de estilo Polaris).

Ejemplos

Consulte las secciones siguientes para ver ejemplos de uso del motor DataLakeCatalog:

Unity Catalog
Unity Catalog con tablas Delta Lake e Iceberg Con use_unity_catalog_v2 = 1, el catálogo unity admite tanto tablas Delta Lake como tablas Iceberg y detecta el formato de cada tabla.

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 acepta una entidad de servicio de OAuth en el formato <client_id>:<client_secret>, un token de acceso personal (dapi...) o un token de OAuth obtenido previamente.

Glue Catalog
OneLake Catalog Puede usarse habilitando 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 autenticarse sin compartir un secret de client, establezca onelake_bearer_token en un token Bearer obtenido previamente (con alcance para https://storage.azure.com) en lugar de onelake_client_id/onelake_client_secret. ClickHouse no actualiza el token, por lo que la base de datos debe volver a crearse después de que caduque.

Referencia de SQL

Tipos de datos

Motores

Funciones

Formatos

Configuración

Tablas del sistema

Lagos de datos

Catálogos compatibles

Crear una base de datos

Ejemplos

​Catálogos compatibles

​Crear una base de datos

​Ejemplos

Catálogos compatibles

Crear una base de datos

Ejemplos