Databricks

Esta página documenta la integración de Anjana Data Platform con Databricks mediante el plugin tot-plugin-databricks. En su Fase 1, la integración habilita el descubrimiento y la extracción de metadatos técnicos (modo read-only) de los activos disponibles en Unity Catalog, sin realizar ninguna mutación sobre el sistema origen.

Modelo de integración

El conector tot-plugin-databricks se integra con Unity Catalog para descubrir activos y extraer su metadata técnica estructurada, adaptándola al metamodelo operativo de Anjana Data Platform. Actúa como un plugin de tipo extractor de metadatos dentro de la arquitectura Tot: se ejecuta bajo su orquestación, implementa los contratos estándar de la plataforma y devuelve la información en el formato requerido. La solución está desacoplada del proveedor cloud (Azure, AWS y GCP), de modo que el mismo código opera contra cualquiera de ellos sin cambios.

El plugin implementa las operaciones definidas en la interfaz estándar ExtractMetadataControllerInterface (tot-plugin-lib), correspondientes a los dos mecanismos de extracción de Tot: descubrimiento (metadataList) y extracción de detalle (metadataExtract).

Activos soportados

La Fase 1 cubre los siguientes tipos de activo de Unity Catalog:

La correspondencia entre cada tipo de activo de Unity Catalog y el subType de objeto con el que se representa en Anjana no está codificada de forma fija: se declara en el bloque technology.mapping del YAML del conector. Los valores por defecto, que se re

comienda no modificar salvo necesidad, son:

El subType resultante determina tanto la profundidad del recorrido en metadataList como el conjunto de atributos que se extraen en metadataExtract —por ejemplo, solo DATASET genera DATASET_FIELDS—. Estos nombres deben coincidir con los subType configurados en el metamodelo de Anjana para que los activos se asocien a la plantilla correcta.

Descubrimiento de activos (metadataList)

La operación metadataList descubre y lista los activos disponibles en Unity Catalog, permitiendo al usuario explorar la jerarquía y seleccionar los activos que desea importar a Anjana Data Platform. El recorrido respeta la jerarquía nativa de Unity Catalog y su profundidad depende del subType solicitado:

• DBK_CATALOG, lista plana de catálogos (nivel raíz).

• DBK_SCHEMA, árbol de dos niveles: catálogo > esquema.

• DATASET, árbol de tres niveles: catálogo > esquema > objeto tabular (tabla, vista, vista materializada, streaming table).

• DBK_VOLUME, árbol de tres niveles: catálogo > esquema > volumen.

El listado se apoya en las APIs REST de Unity Catalog (GET /api/2.1/unity-catalog/{catalogs|schemas|tables|volumes}) y aplica paginación mediante max_results y page_token, iterando hasta agotar next_page_token, con un tope de seguridad de páginas por operación configurable en maxPages (por defecto 1000) para evitar paginaciones infinitas. Para acotar el coste del descubrimiento masivo, en /tables pueden emplearse los parámetros omit_columns=true y omit_properties=true. El resultado se devuelve ordenado de forma determinista por name ascendente en cada nivel y deduplicado por identificador técnico.

Extracción de metadatos (metadataExtract)

La operación metadataExtract recupera los metadatos técnicos detallados de un activo concreto, previamente seleccionado mediante metadataList, y los transforma al modelo de Anjana. La ruta jerárquica del activo a extraer se parsea con el separador configurado en pathSeparator del YAML y se convierte internamente al identificador técnico completo (FQN) de Databricks.

Para cada activo dentro del alcance, el plugin recupera —siempre que estén disponibles vía API— los siguientes metadatos:

• physicalName, identificador técnico completo (FQN) del activo.

• name, nombre del activo.

• path, ruta jerárquica completa (usa pathSeparator).

• description, descripción cuando exista.

• owner, propietario del activo.

• createdAt, fecha de creación (epoch ms), cuando la API la exponga.

• tags, etiquetas a nivel de activo.

En activos tabulares (DATASET), el plugin recupera además la estructura de columnas como DATASET_FIELDS, incluyendo nombre, tipo de dato nativo, posición, nulabilidad, descripción y tags de columna. La numeración de columnas se transforma de base 0 (Databricks) a base 1 (Anjana) durante el mapeo. La operación es atómica: devuelve el resultado completo del activo o un error, sin resultados parciales.

Mapeo a atributos de Anjana

Los atributos extraídos se mapean a entradas de entityAttributes en Anjana. Los atributos a crear en la configuración funcional de Anjana deben tener los siguientes tipos (los nombres deben coincidir en la tabla attribute Definition, campo name, para que aparezcan en la plantilla).

DATASET (Table, View, Materialized View, Streaming Table.. en Databricks)

DATASET_FIELD (Estructura de columnas de las entidades tabulares de Databricks)

Para los campos de los activos tabulares (DATASET_FIELDS) se mapean además:

DBK_CATALOG (Catalog en Databricks)

DBK_SCHEMA (Schema en Databricks)

Activos con caracteres especiales en el nombre

Unity Catalog permite caracteres como / en el nombre de los activos. Si se utilizan, debe configurarse pathSeparator con un carácter distinto de / para garantizar una construcción correcta del atributo path. Puede emplearse cualquier carácter excepto :.

El pathSeparator del plugin de Databricks debe coincidir con el del resto de plugins así como con el Seprador de path de extracción de Kerno y Tot.

Credenciales y privilegios requeridos

Descubrimiento y extracción de metadatos

La integración requiere un Service Principal con permisos de solo lectura sobre los activos que se desean gobernar. Es responsabilidad del cliente:

• Service Principal, con los privilegios de lectura sobre Unity Catalog necesarios para el descubrimiento y la extracción de metadatos en Fase 1 (ver el detalle en Privilegios requeridos en Unity Catalog).

• Workspace de gobierno (playground) y activos accesibles para la entidad técnica utilizada por el plugin (ver Aprovisionamiento del workspace de gobierno).

• Configuración correcta de credenciales en el YAML del conector.

La visibilidad efectiva de los activos depende de los permisos jerárquicos del Service Principal en Unity Catalog y de la configuración del workspace desde el que se opera.

Privilegios requeridos en Unity Catalog

Disponer de un Service Principal no es suficiente: para que las APIs de Unity Catalog respondan, la identidad debe tener concedidos explícitamente los privilegios que permiten recorrer la jerarquía y leer los metadatos de cada activo. El modelo de privilegios de Unity Catalog es jerárquico, de modo que para alcanzar una tabla o un volumen es imprescindible poder atravesar antes su catálogo y su esquema.

Los privilegios mínimos que exige la API son:

En síntesis, la credencial necesita siempre USE CATALOG y USE SCHEMA para navegar la jerarquía, y adicionalmente SELECT sobre las tablas o READ VOLUME sobre los volúmenes que se deseen gobernar, según el tipo de activo. Al tratarse de privilegios jerárquicos, pueden concederse a nivel de catálogo o de esquema para que apliquen en cascada sobre los objetos contenidos.

Aprovisionamiento del workspace de gobierno (playground)

El plugin opera siempre desde un workspace de Databricks, por lo que su aprovisionamiento es un requisito previo tan crítico como las propias credenciales. Es responsabilidad del cliente disponer de un workspace de gobierno —comúnmente denominado playground— que actúe como punto único de acceso del plugin a Unity Catalog.

Para que el descubrimiento y la extracción funcionen, ese workspace debe cumplir dos condiciones:

• Habilitación del Service Principal, la identidad técnica utilizada por el plugin debe estar dada de alta y habilitada en el workspace de gobierno.

• Accesibilidad de los activos, los catálogos y activos que se desean gobernar deben estar vinculados y ser accesibles desde ese workspace. En Unity Catalog, un catálogo no vinculado al workspace no es visible aunque el Service Principal tenga privilegios sobre él.

La visibilidad efectiva de un activo es, por tanto, la intersección de dos condiciones independientes: que el Service Principal tenga los privilegios de Unity Catalog descritos en el apartado anterior, y que el activo sea accesible desde el workspace de gobierno. Si falta cualquiera de las dos, el activo no aparecerá en el descubrimiento.

Autenticación y autorización

El plugin se autentica contra Databricks mediante OAuth 2.0 Client Credentials con Service Principal. La diferencia entre proveedores cloud se limita a cómo se obtiene el Bearer Token; la lógica funcional permanece desacoplada y la estrategia se resuelve por configuración mediante el parámetro authType del YAML. No se contemplan tokens personales (PAT) ni credenciales de usuario.

Los parámetros de conexión y autenticación se definen en technology.credential dentro de cada conexión del YAML del conector:

Databricks OAuth M2M (estrategia principal)

Databricks expone un proveedor OIDC nativo en cada workspace, al que el plugin solicita el token directamente (POST {host}/oidc/v1/token). Es la estrategia recomendada porque funciona igual en Azure, AWS y GCP, solo requiere host, clientId y clientSecret, y no depende de proveedores externos. Se selecciona con authType: "databricks-oauth".

Paso 1: Crear el Service Principal en Databricks

• Acceder a Databricks Account Console → User Management → Service Principals.
• Crear un nuevo Service Principal

Más detalle en la documentación oficial de Azure Databricks: https://learn.microsoft.com/en-us/azure/databricks/dev-tools/auth/oauth-m2m

Paso 2: Generar credenciales OAuth

• Generar un OAuth Secret para el Service Principal.

• Anotar para incorporar al YAML los siguientes valores:

  • clientId (aplicación Id)

  • clientSecret (crear secreto de autenticación en la sección de Secrets)

Paso 3: Conceder privilegios mínimos sobre los activos de Unity Catalog

Conceder los privilegios indicados en Privilegios requeridos en Unity Catalog.

Paso 4: Configurar el YAML del plugin

Trasladar al YAML:

• Tipo de autorización authType: "databricks-oauth"

• Host

• Client ID / Application Id (obtenidos en Databricks Account en Paso 2)

• Client Secret (obtenidos en Databricks Account en Paso 2)

Azure Entra ID (estrategia alternativa)

Autenticación mediante Service Principal de Azure Entra ID (POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token), recomendada en entornos exclusivamente Azure que deseen reutilizar una identidad existente. Se selecciona con authType: "azure-sp" y requiere adicionalmente el tenant.

Los parámetros de conexión y autenticación se definen en technology.credential dentro de cada conexión del YAML del conector:

Paso 1: Crear una App Registration en Microsoft Entra ID

• Microsoft Entra ID → App registrations.
• Registrar una nueva aplicación.

Paso 2: Crear un Client Secret

• Generar un Client Secret.

• Anotar para incorporar al YAML los siguientes valores:

  • tenantId

  • clientId

  • clientSecret

Paso 3: Dar de alta el Service Principal en Databricks

Dar de alta la aplicación de Entra ID como Service Principal en Databricks (Account Console o mediante SCIM/API, según la administración del entorno) y seguir el resto de los pasos solicitados por la configuración para dar de alta el Service Principal dentro de Databricks

Más información en: https://learn.microsoft.com/en-us/azure/databricks/admin/users-groups/manage-service-principals

Paso 4: Asignar el Service Principal al Workspace

Añadir el Service Principal al Workspace correspondiente

Paso 5: Conceder permisos mínimos

Conceder los privilegios indicados en Privilegios requeridos en Unity Catalog.

Paso 6: Configurar el YAML del plugin

Trasladar al YAML:

• Tipo de autorización authType: "azure-sp"

• Host

• Tenant (obtenidos en Azure en Paso 2)

• Client ID / Application Id (obtenidos en Azure en Paso 2)

• Client Secret (obtenidos en Azure en Paso 2)

Gestión de errores y reintentos

El plugin distingue entre errores funcionales (validación de entrada, subType no soportado, formato de element incorrecto), que no se reintentan, y errores técnicos transitorios (red, HTTP 5xx, throttling), que se reintentan según una política configurable. En metadataList se toleran errores parciales por ámbito (catálogo/esquema) para maximizar la cobertura del descubrimiento; en metadataExtract no se admiten resultados parciales.

La política de reintentos se define por conexión mediante databricksCountRetry (número máximo de reintentos) y databricksWaitRetry (espera base, en segundos, entre reintentos). En errores 429 con cabecera Retry-After, el plugin respeta dicho valor; en su ausencia, aplica back-off exponencial a partir de databricksWaitRetry.

Configuración

Conectividad

La conectividad del plugin se realiza contra las APIs REST de Unity Catalog (/api/2.1/unity-catalog/...) sobre el host del workspace de Databricks. Los dominios varían según el cloud:

• Azure: https://adb-xxxx.azuredatabricks.net

• AWS: https://xxxx.cloud.databricks.com

• GCP: https://xxxx.gcp.databricks.com

Multi-conexión

El plugin soporta múltiples conexiones a distintos workspaces o entornos de Databricks. Cada conexión se identifica de forma única mediante la terna infrastructure / technology / zone (modelo ARI), donde zone actúa como discriminador lógico. Se recomienda configurar un workspace dedicado a gobierno (playground) como punto central de acceso bajo un único ARI.

El separador que Anjana utiliza para recuperar los valores de un atributo de tipo lista (por ejemplo, los tags) se controla mediante attributeSeparator. Normalmente no es necesario modificarlo.

Rendimiento y límites

El plugin regula la carga que ejerce sobre las APIs de Unity Catalog mediante dos bloques del YAML, con valores por defecto razonables que normalmente no requieren ajuste:

• rate-limit, limita el ritmo de llamadas con requests-per-second (peticiones por segundo) y timeout-seconds (tiempo máximo de espera por petición).

• concurrency, controla el paralelismo del descubrimiento y de la recuperación de tags mediante listing-threads y listing-batch-size (listado) y tags-threads y tags-batch-size (tags).

Adicionalmente, maxPages acota el número máximo de páginas por operación (por defecto 1000), como salvaguarda frente a paginaciones no acotadas.

Anexo

Más información sobre las APIs:

https://docs.databricks.com/api/workspace/catalogs/list

https://docs.databricks.com/api/workspace/schemas/list

https://docs.databricks.com/api/workspace/tables/list

https://docs.databricks.com/api/workspace/volumes/list

https://docs.databricks.com/api/workspace/catalogs/list

https://docs.databricks.com/api/workspace/schemas/list

https://docs.databricks.com/api/workspace/tables/list

https://docs.databricks.com/api/workspace/volumes/list