Conexión a un catálogo de datos

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:

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 Delta e Iceberg de Unity Catalog que usan ubicaciones de almacenamiento externo.

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).

Con las credenciales, puede conectarse al endpoint correspondiente para consultar las tablas en Iceberg o 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';

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

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.

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

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://...')

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.