Conexión a un catálogo de datos

Conecta ClickHouse a catálogos de datos externos mediante el motor de base de datos DataLakeCatalog para exponer las tablas del catálogo como bases de datos nativas de ClickHouse.

En la sección anterior, consultaste formatos de tabla abiertos pasando las rutas de almacenamiento directamente. En la práctica, la mayoría de las organizaciones gestionan los metadatos de las tablas mediante un catálogo de datos: un registro central que realiza un seguimiento de las ubicaciones de las tablas, los esquemas y las particiones. Cuando conectas ClickHouse a un catálogo mediante el motor de base de datos DataLakeCatalog, el catálogo completo se expone como una base de datos de ClickHouse. Cada tabla del catálogo aparece automáticamente y puede consultarse con toda la potencia de ClickHouse SQL, sin necesidad de conocer la ruta de cada tabla ni de gestionar credenciales para cada una.

Esta guía explica cómo conectarse a Databricks Unity Catalog. ClickHouse también es compatible con los siguientes catálogos; consulta cada guía de referencia para ver las instrucciones completas de configuración:

Catálogo	Guía de referencia
AWS Glue	AWS Glue catalog
Iceberg REST Catalog	REST catalog
Lakekeeper	Lakekeeper catalog
Project Nessie	Nessie catalog
Microsoft OneLake	Fabric OneLake

​

Conectarse a Unity Catalog

A modo de ejemplo, usaremos Unity Catalog.

Databricks Unity Catalog proporciona una gobernanza centralizada para los datos de lakehouse de Databricks.

Databricks admite múltiples formatos de datos para su lakehouse. Con ClickHouse, puede consultar tablas de Unity Catalog tanto en formato Delta como Iceberg.

La integración con Unity Catalog funciona con tablas administradas y externas. Actualmente, esta integración solo se admite en AWS.

​

Configuración de Unity en Databricks

Para permitir que ClickHouse interactúe con Unity Catalog, debe asegurarse de que Unity Catalog esté configurado para permitir la interacción con un lector externo. Esto se puede lograr siguiendo la guía “Enable external data access to Unity Catalog”.

Además de habilitar el acceso externo, asegúrese de que el principal que configura la integración tenga el privilegio EXTERNAL USE SCHEMA sobre el esquema que contiene las tablas.

Una vez configurado el catálogo, debe generar credenciales para ClickHouse. Se pueden usar dos métodos distintos, según el modo de interacción con Unity:

• Para clientes de Iceberg, autentíquese con un service principal.

• Para clientes de Delta, use un token de acceso personal (PAT).

​

Conexión al catálogo

Con las credenciales, puede conectarse al endpoint correspondiente para consultar las tablas en Iceberg o Delta.

Delta

Debe usar Unity Catalog para acceder a los datos en formato Delta.

SET allow_experimental_database_unity_catalog = 1;

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';

Iceberg

SET allow_database_iceberg = 1;

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';

​

Listar tablas

Una vez establecida la conexión con su catálogo, puede ver la lista de tablas.

SHOW TABLES FROM unity

┌─name───────────────────────────────────────────────┐
│ unity.logs                                         │
│ unity.single_day_log                               │
└────────────────────────────────────────────────────┘

31 rows in set.

​

Explorar los esquemas de las tablas

Podemos usar el comando estándar SHOW CREATE TABLE para ver cómo se crearon las tablas.

Se requieren comillas invertidas

Tenga en cuenta que es necesario especificar el espacio de nombres y el nombre de la tabla entre comillas invertidas; ClickHouse no admite más de un espacio de nombres.

A continuación se asume que se consulta el catálogo REST de Iceberg:

SHOW CREATE TABLE unity.`icebench.single_day_log`

CREATE TABLE unity.`icebench.single_day_log`
(
    `pull_request_number` Nullable(Int64),
    `commit_sha` Nullable(String),
    `check_start_time` Nullable(DateTime64(6, 'UTC')),
    `check_name` Nullable(String),
    `instance_type` Nullable(String),
    `instance_id` Nullable(String),
    `event_date` Nullable(Date32),
    `event_time` Nullable(DateTime64(6, 'UTC')),
    `event_time_microseconds` Nullable(DateTime64(6, 'UTC')),
    `thread_name` Nullable(String),
    `thread_id` Nullable(Decimal(20, 0)),
    `level` Nullable(String),
    `query_id` Nullable(String),
    `logger_name` Nullable(String),
    `message` Nullable(String),
    `revision` Nullable(Int64),
    `source_file` Nullable(String),
    `source_line` Nullable(Decimal(20, 0)),
    `message_format_string` Nullable(String)
)
ENGINE = Iceberg('s3://...')

​

Consultar una tabla

Se admiten todas las funciones de ClickHouse. De nuevo, el espacio de nombres y el nombre de la tabla deben ir entre comillas invertidas.

SELECT count()
FROM unity.`icebench.single_day_log`

┌───count()─┐
│ 282634391 │ -- 282.63 millones
└───────────┘

1 fila en el conjunto. Elapsed: 1.265 sec.

Para ver las instrucciones completas de configuración, consulta la guía de referencia de Unity Catalog.