Generador automático de comentarios de negocio para esquemas, tablas y columnas de Unity Catalog usando Foundation Model API de Databricks.
Estado: v6 — scope desde tabla de control, soporte multi-catálogo y proceso de auditoría independiente.
- ¿Qué hace?
- Pipelines
- Estructura del repositorio
- Quick start
- Configuración mínima para pruebas
- Parámetros
- Tabla de scope
- Insumos de contexto
- Tablas de resultados
- Flujo de revisión
- Auditoría de comentarios
- Dashboard
- Desarrollo
- Roadmap
- Release notes
- Lee una tabla de control (scope) que indica qué tablas de Unity Catalog se deben documentar. Las tablas pueden vivir en distintos catálogos.
- Genera comentarios de negocio en español para esquemas, tablas y columnas usando un modelo fundacional (default:
databricks-claude-sonnet-4-5). - Usa como contexto archivos del directorio
input/y/o tablas del lakehouse listadas eninput/mapping.md. - Opcionalmente, muestrea datos reales de cada tabla para enriquecer el prompt.
- Persiste resultados en una tabla
resultadoscon camposstatusyuser_commentspara flujo de revisión. - Aplica al catálogo los comentarios con
status='aprobado'(default) víaCOMMENT ON SCHEMA / TABLEyALTER TABLE ... ALTER COLUMN. Soporta múltiples catálogos en una sola corrida. - (Opcional) Audita los comentarios generados contra los insumos provistos y un catálogo de criterios declarativo, escribiendo el veredicto en
criterio_fallidoydetalles_criterio_fallido.
El bundle define dos jobs independientes:
┌──────────────────┐ ┌────────────────────┐ ┌──────────────────┐
│ setup_schema │───▶│ generate_comments │───▶│ apply_comments │
│ (DDL) │ │ (LLM + persiste) │ │ (status=aprobado)│
└──────────────────┘ └────────────────────┘ └──────────────────┘
│ │ │
▼ ▼ ▼
ejecuciones / scope_table COMMENT ON / ALTER
resultados + information_schema sobre Unity Catalog
+ Foundation Model API
Por defecto todos los comentarios se insertan con status='aprobado', así que el pipeline ejecuta de punta a punta. Para un flujo con revisión humana ver Flujo de revisión.
┌──────────────────┐
│ audit_comments │ Lee resultados + insumos (mapping.md +
│ (LLM auditor) │ audit_mapping.md) y escribe veredicto en
└──────────────────┘ criterio_fallido / detalles_criterio_fallido.
Independiente del job principal. No modifica status ni el contenido del comentario.
dbx-comments-gen/
├── databricks.yml # Bundle: jobs, dashboard, vars, targets
├── README.md
├── CLAUDE.md # Instrucciones para Claude Code
├── .gitignore
├── input/
│ ├── mapping.md # Insumos: archivos y tablas
│ ├── audit_mapping.md # Insumos extra solo para auditoría
│ └── (documentos del usuario)
└── src/
├── 01_setup_schema.py # DDL: esquema + ejecuciones + resultados
├── 02_generate_comments.py # Generador con IA (desde scope_table)
├── 03_apply_comments.py # Aplicador multi-catálogo
├── 04_audit_comments.py # Auditor independiente
├── audit_criteria.py # Catálogo declarativo de criterios
└── dashboard.lvdash.json # Dashboard Lakeview
- Databricks CLI v0.200+ con un perfil autenticado.
- Workspace con permisos para crear catálogos, esquemas, jobs y dashboards.
- Un SQL Warehouse disponible.
- Una tabla de scope existente en Unity Catalog (ver Tabla de scope).
Edita databricks.yml y reemplaza los placeholders en targets::
targets:
dev:
workspace:
host: https://<tu-workspace>.azuredatabricks.net
prod:
workspace:
host: https://<tu-workspace-prod>.azuredatabricks.netEdita input/mapping.md. Soporta dos secciones:
# Archivos
`diccionario.docx`: Diccionario de datos oficial
`reglas_negocio.md`: Reglas de negocio por dominio
# Tablas
main.referencia.glosario_negocio: Glosario corporativo de términos
main.referencia.taxonomia_productos: Taxonomía de productosColoca los archivos referenciados en input/. Si una tabla no es accesible, el proceso emite warning y continúa sin ella.
# Validar
databricks bundle validate --target dev --profile <profile>
# Desplegar
databricks bundle deploy --target dev --profile <profile>
# Ejecutar el pipeline de generación + aplicación
databricks bundle run comments_pipeline --target dev --profile <profile> \
--params scope_table=main.control.scope_documentacion,\
scope_catalog_column=catalog_name,\
scope_schema_column=schema_name,\
scope_table_column=table_name,\
results_catalog=mi_resultados,\
results_schema=ai_comments,\
enable_sampling=yes,sampling_pct=15
# (Opcional) Ejecutar la auditoría sobre los comentarios persistidos
databricks bundle run comments_audit_pipeline --target dev --profile <profile> \
--params results_catalog=mi_resultados,results_schema=ai_commentsEl cuello de botella del pipeline es la latencia del Foundation Model API, no Spark. El loop es secuencial por columna y no aprovecha paralelismo, así que conviene un cluster mínimo y barato para validar end-to-end.
Funciona en cualquier workspace. Configuración recomendada para new_cluster en databricks.yml:
new_cluster: &single_node_cluster
spark_version: "15.4.x-scala2.12"
num_workers: 0
node_type_id: "Standard_D4ads_v5" # 4 vCPU / 16 GB — ~30% más barato que DS3_v2
data_security_mode: "SINGLE_USER" # requerido para UC + identity columns
runtime_engine: "STANDARD" # Photon off (no aporta a este workload)
spark_conf:
spark.master: "local[*, 4]"
spark.databricks.cluster.profile: "singleNode"
custom_tags:
ResourceClass: "SingleNode"
project: "dbx-comments-gen"Si está habilitado en el workspace, es la opción más simple y de arranque más rápido (< 30 s). Reemplaza el bloque new_cluster: *single_node_cluster de cada tarea por:
- task_key: setup_schema
description: "Crea esquema y tablas de control"
notebook_task:
notebook_path: src/01_setup_schema.py
base_parameters:
results_catalog: "{{job.parameters.results_catalog}}"
results_schema: "{{job.parameters.results_schema}}"
source: WORKSPACE
# ← sin new_cluster: serverless se infiere por ausencia de computeAplicar el mismo cambio a las tareas generate_comments, apply_comments y audit_comments.
SQL Warehouse Serverless 2X-Small con auto-stop a 10 min es suficiente — las queries son agregaciones simples sobre dos tablas Delta pequeñas.
Para validar el pipeline end-to-end con el menor costo posible:
- Scope table chiquita: 1–2 tablas con pocas columnas (≤ 20). El costo crece linealmente con
tablas × columnas. enable_sampling=noen la primera corrida — evita queries adicionales a las tablas a documentar.- Mantener
model_endpoint=databricks-claude-sonnet-4-5(pago por token, sin endpoint dedicado). - Correr solo
setup_schema + generate_commentsprimero (desde la UI del job, deseleccionarapply_comments) para revisar los comentarios antes de aplicarlos al catálogo. - La auditoría (
comments_audit_pipeline) es opcional — saltarla en la primera prueba.
| Parámetro | Descripción | Default |
|---|---|---|
scope_table |
Tabla de control catalogo.esquema.tabla con los objetos a documentar |
(obligatorio) |
scope_catalog_column |
Nombre de la columna de scope_table que contiene el catálogo |
(obligatorio) |
scope_schema_column |
Nombre de la columna que contiene el esquema | (obligatorio) |
scope_table_column |
Nombre de la columna que contiene la tabla | (obligatorio) |
model_endpoint |
Endpoint del modelo fundacional | databricks-claude-sonnet-4-5 |
results_catalog |
Catálogo donde se guardan los resultados | (obligatorio) |
results_schema |
Esquema donde se guardan los resultados | (obligatorio) |
enable_sampling |
Habilitar muestreo de datos reales (yes/no) |
no |
sampling_pct |
Porcentaje para tablas > 500 registros (1-100) | (requerido si sampling=yes) |
| Parámetro | Descripción | Default |
|---|---|---|
results_catalog |
Catálogo donde está la tabla resultados |
(obligatorio) |
results_schema |
Esquema donde está la tabla resultados |
(obligatorio) |
id_ejecucion |
ID de ejecución a auditar. Vacío = todas las filas | (vacío) |
audit_only_approved |
Auditar solo filas con status='aprobado' (yes/no) |
yes |
audit_model_endpoint |
Modelo a usar como auditor | databricks-claude-sonnet-4-5 |
A partir de v6 el generador no recorre un catálogo completo, sino que lee una tabla de control suministrada por el usuario. Esto permite:
- Documentar tablas de múltiples catálogos en una sola corrida.
- Mantener listas curadas de objetos a documentar (por dominio, por proyecto, por sprint…).
- Versionar el alcance fuera del notebook.
La tabla debe tener al menos tres columnas con los nombres del catálogo, esquema y tabla. Los nombres exactos se configuran vía parámetros (scope_catalog_column, scope_schema_column, scope_table_column).
Ejemplo:
CREATE TABLE main.control.scope_documentacion (
catalog_name STRING,
schema_name STRING,
table_name STRING,
prioridad INT,
dominio STRING
);
INSERT INTO main.control.scope_documentacion VALUES
('ventas', 'mart', 'fact_pedidos', 1, 'comercial'),
('ventas', 'mart', 'dim_cliente', 1, 'comercial'),
('finanzas', 'staging', 'movimientos', 2, 'finanzas');Filas con valores nulos o vacíos en cualquiera de las tres columnas se omiten. Las combinaciones (catalogo, esquema, tabla) se deduplican automáticamente. Si una tabla del scope no existe o no se tiene permiso, se omite con warning.
Formatos: .docx, .tsv, .csv, .xlsx, .txt, .md, .json, .yaml.
# Archivos
`diccionario.docx`: Diccionario oficialTablas de Unity Catalog en formato catalogo.esquema.tabla: descripción. Se cargan las primeras 200 filas como texto.
# Tablas
main.referencia.glosario_negocio: Glosario corporativoSi una tabla no existe o no se tiene permiso, se emite un warning y el proceso continúa.
Dentro de la descripción se pueden incluir hints entre corchetes para acotar qué cargar:
| Insumo | Sintaxis | Efecto |
|---|---|---|
Excel (.xls / .xlsx) |
[tabs: tab1, tab2] |
Lee solo esas hojas |
| Tabla UC | [columnas: col1, col2] |
Selecciona solo esas columnas |
Alias aceptados (case-insensitive): tab/tabs/hoja/hojas/sheet/sheets; columna/columnas/column/columns/campo/campos/field/fields.
Ejemplos:
# Archivos
`catalogo_productos.xlsx`: Catálogo vigente. [tabs: productos, sub_productos]
# Tablas
main.referencia.glosario: Glosario corporativo. [columnas: termino, definicion, dominio]Si una hoja del Excel no existe, el proceso emite un warning y continúa con las hojas restantes. Si una columna especificada no existe, la query falla y la tabla se omite (con warning).
Cada insumo recibe un score por esquema/tabla:
- +10 si el nombre del esquema aparece en contenido/nombre/descripción.
- +15 si el nombre de la tabla aparece.
- +4 si es tabla del lakehouse.
- +3 si es
.docx; +2 si es.tsv; +1.5 si es.md/.txt. - +1 por keyword en la descripción (
definic,negocio,regla,glosario,taxonom, etc.).
Los insumos se concatenan en orden descendente respetando un límite de 30K caracteres (~7.500 tokens). El último se trunca si no cabe.
Se crean automáticamente en {results_catalog}.{results_schema}.
| Columna | Tipo | Descripción |
|---|---|---|
id_ejecucion |
STRING (PK) | GUID único de la ejecución |
fecha_ejecucion |
TIMESTAMP | Fecha/hora UTC |
estado |
VARCHAR(50) | INICIADO, EN_PROCESO, COMPLETADO, COMPLETADO_CON_ERRORES, ERROR |
resultado |
VARCHAR(4000) | Detalle del resultado o errores |
| Columna | Tipo | Descripción |
|---|---|---|
id_resultado |
BIGINT (PK, identity) | ID autoincrementable |
id_ejecucion |
STRING (FK) | Referencia a ejecuciones.id_ejecucion |
fecha_resultado |
TIMESTAMP | Fecha/hora UTC de generación |
nombre_catalogo |
VARCHAR(255) | Catálogo de la tabla procesada |
nombre_esquema |
VARCHAR(255) | Esquema procesado |
nombre_tabla |
VARCHAR(255) | Tabla procesada (__esquema__ para esquemas) |
nombre_columna |
VARCHAR(255) | Columna procesada (__tabla__ para tablas, __esquema__ para esquemas) |
comentario |
VARCHAR(4000) | Comentario generado por IA |
status |
VARCHAR(20) | por revisar, aprobado (default), rechazado |
user_comments |
VARCHAR(4000) | Comentarios del revisor (vacío por defecto) |
criterio_fallido |
STRING | Criterio de auditoría fallido (NULL si OK). Lo escribe 04_audit_comments |
detalles_criterio_fallido |
STRING | Justificación del criterio fallido (NULL si OK) |
Ambas tablas tienen delta.enableChangeDataFeed = true. La columna status tiene un CHECK constraint para los tres valores permitidos.
El default status='aprobado' significa que el pipeline aplica automáticamente todos los comentarios generados. Para revisar antes de aplicar:
- Ejecutar solo
setup_schema+generate_comments(desde la UI de Databricks, seleccionar y correr solo esas tareas). - (Opcional) Correr la auditoría (
comments_audit_pipeline) para obtener un primer screening automático. - Revisar y actualizar los registros:
UPDATE my_results.ai_comments.resultados SET status = 'por revisar', user_comments = 'Pendiente validación con stakeholder' WHERE id_ejecucion = '<exec-id>' AND nombre_tabla = 'cliente'; UPDATE my_results.ai_comments.resultados SET status = 'rechazado', user_comments = 'El término no aplica para nuestro negocio' WHERE id_resultado IN (123, 456);
- Aprobar lo que esté bien:
UPDATE my_results.ai_comments.resultados SET status = 'aprobado' WHERE id_ejecucion = '<exec-id>' AND status = 'por revisar';
- Ejecutar
apply_comments(manualmente desde la UI), opcionalmente filtrando porid_ejecucion.
A partir de v6 existe un proceso independiente (04_audit_comments.py, expuesto como job comments_audit_pipeline) que evalúa cada comentario contra los insumos provistos usando un LLM como auditor.
- Carga insumos de
input/mapping.mdyinput/audit_mapping.md(este último es opcional y solo lo lee la auditoría — útil para glosarios estrictos, lineamientos editoriales, ejemplos correctos/incorrectos, etc.). - Lee las filas de
resultados(filtrables porid_ejecuciony porstatus='aprobado'). - Para cada fila construye un prompt con el contexto relevante y le pide al modelo un veredicto en JSON.
- Si el comentario está bien: escribe
NULLencriterio_fallido/detalles_criterio_fallido(idempotente — borra veredictos previos). - Si falla un criterio: escribe el
iddel criterio encriterio_fallidoy una justificación corta endetalles_criterio_fallido.
Nunca modifica status ni el contenido del comentario. La decisión final de aprobar/rechazar sigue siendo humana.
Definido de forma declarativa en src/audit_criteria.py. Para agregar/quitar/modificar un criterio basta editar ese archivo:
| ID | Detecta |
|---|---|
FUERA_DE_CONTEXTO |
Afirmaciones no respaldadas por los insumos (alucinación). |
TERMINOLOGIA_INCORRECTA |
Uso de términos distintos a los canónicos del glosario. |
GRANULARIDAD |
Comentario con nivel incorrecto (p. ej. una columna describe la tabla). |
IDIOMA_O_ESTILO |
Idioma, longitud, formato markdown, prefijos tipo Definición:, etc. |
INFORMACION_FALTANTE |
Omite información clave disponible en los insumos. |
Cada criterio tiene un id (string corto en MAYÚSCULAS) y un description que se inyecta literalmente en el prompt del auditor.
# Auditar todas las filas aprobadas
databricks bundle run comments_audit_pipeline --target dev --profile <profile> \
--params results_catalog=mi_resultados,results_schema=ai_comments
# Auditar una ejecución específica, incluyendo no-aprobadas
databricks bundle run comments_audit_pipeline --target dev --profile <profile> \
--params results_catalog=mi_resultados,results_schema=ai_comments,\
id_ejecucion=<exec-id>,audit_only_approved=noSi la auditoría se lanza directamente después de generate_comments (encadenada manualmente o desde una orquestación externa), toma automáticamente el id_ejecucion mediante taskValues.
Recurso DAB: comments_dashboard (archivo src/dashboard.lvdash.json).
Totalmente parametrizado: las queries usan IDENTIFIER(:results_catalog || '.' || :results_schema || '.<tabla>') para resolver dinámicamente las tablas de resultados, así que el mismo dashboard sirve para cualquier deploy.
Parámetros del dashboard:
| Parámetro | Descripción |
|---|---|
results_catalog |
Catálogo donde están las tablas de resultados |
results_schema |
Esquema donde están las tablas de resultados |
fecha |
Filtra todo por fecha de ejecución |
catalogo |
Filtra por catálogo procesado |
esquema |
Filtra por esquema procesado |
tabla |
Filtra por tabla procesada (multi-select) |
status |
Filtra por estado de revisión |
Al abrir el dashboard por primera vez, hay que seleccionar results_catalog y results_schema; Lakeview persiste la selección.
Widgets:
- Filtros: catálogo/esquema (dataset), fecha, catálogo, esquema, tabla, status.
- KPIs: ejecuciones, comentarios, catálogos, esquemas, tablas, aprobados, por revisar, rechazados.
- Tabla: historial de ejecuciones.
- Tabla: detalle de comentarios (incluye
status,user_comments,criterio_fallidoydetalles_criterio_fallido).
- Python: alineado a PEP 8.
- SQL: identificadores escapados con backticks (soporta nombres con guiones).
- Notebooks: estructurados en etapas numeradas con
MAGIC %md. - Prompts: en español, persona "experto en documentación de datos de una organización", instrucción explícita de no usar conocimiento previo.
| Quieres cambiar... | Edita... |
|---|---|
| Prompt enviado al modelo generador | 02_generate_comments.py → generate_*_comment |
| Prompt del auditor | 04_audit_comments.py → audit_row |
| Catálogo de criterios | audit_criteria.py → AUDIT_CRITERIA |
| Scoring de relevancia | 02_generate_comments.py → _score_relevance |
| Límite de contexto | 02_generate_comments.py / 04_audit_comments.py → MAX_CONTEXT_CHARS |
| Reglas de sampling | 02_generate_comments.py → get_table_sample |
| Esquema de tablas de control | 01_setup_schema.py |
| Lógica de aplicación | 03_apply_comments.py → apply_comment |
| Parámetros expuestos | databricks.yml + widgets de cada notebook |
| Target | Modo | Notas |
|---|---|---|
dev |
development | Default. |
prod |
production | Override de host (y variables si aplica). |
- Modo dry-run — generar prompts sin invocar al modelo (debug).
- Reintentos con backoff exponencial cuando el endpoint falla.
- Paralelismo en generación de columnas dentro de una tabla.
- Auditoría → status automático (opt-in para mover a
por revisarcuando hay observación). - Soporte multilenguaje (
output_language=es|en|pt). - Marcador de "aplicado" en
resultadospara evitar reaplicar.
- Scope desde tabla de control: el generador ya no recorre catálogos completos. Lee una tabla configurable (
scope_table+ tres columnas con catálogo/esquema/tabla) y procesa exactamente esos objetos. Permite mezclar varios catálogos en una sola corrida. - Soporte multi-catálogo: la tabla
resultadosahora persistenombre_catalogo, yapply_commentsaplica los comentarios al catálogo correcto fila por fila. - Proceso de auditoría (
04_audit_comments.py+ jobcomments_audit_pipeline): notebook independiente que evalúa los comentarios contra los insumos provistos usando un LLM, escribe veredicto encriterio_fallido/detalles_criterio_fallidoy es idempotente. - Catálogo declarativo de criterios en
src/audit_criteria.py(FUERA_DE_CONTEXTO,TERMINOLOGIA_INCORRECTA,GRANULARIDAD,IDIOMA_O_ESTILO,INFORMACION_FALTANTE). - Nuevo archivo de insumos
input/audit_mapping.md: insumos extra que solo carga la auditoría (glosarios estrictos, lineamientos editoriales, ejemplos buenos/malos, etc.). - Dashboard ampliado: filtro y KPI por
catalogo, columnasCriterio fallidoyDetalles criterio fallidoen la tabla de detalle.
- Pipeline completo: nueva tarea
apply_commentsque aplica al catálogo los comentarios constatus='aprobado'. - Tablas como insumo:
input/mapping.mdahora soporta una sección# Tablascon tablas de Unity Catalog. Si no son accesibles, warning y continúa. - Flujo de revisión: nuevas columnas
status(por revisar/aprobado/rechazado, defaultaprobado) yuser_commentsenresultados. - Parámetros sin defaults: solo
model_endpointtiene default. El resto debe especificarse explícitamente. - PEP 8 en todos los archivos.
- Estructura compactada: aplanado
src/(eliminadossrc/notebooks/,src/pipelines/,src/__init__.pyysrc/pipelines/01_repositorio_resultados.sql). - .gitignore ampliado (notebooks/IDE/Terraform/Databricks bundle locks).
- Dashboard dinámico: queries con
IDENTIFIER(:results_catalog || '.' || :results_schema || ...), filtro destatus, KPIs de aprobados/por revisar/rechazados, columnasstatusyuser_commentsen la tabla de detalle. - Hints en mapping.md: la descripción de cada insumo acepta
[tabs: ...](Excel multi-hoja) y[columnas: ...](tablas UC) para acotar la carga.
- Dashboard desplegado como recurso DAB.
- Tarea
setup_schemaagregada al job. - Backtick quoting en todos los identificadores SQL.
- Soporte para
.xlsx(openpyxl). - Prompt: instrucción explícita de usar solo el contexto provisto.
- Recorrido por catálogo completo (esquema opcional).
- Comentarios a nivel de esquema (no solo tabla/columna).
- Modelo, catálogo y esquema de resultados parametrizables.
- Auto-provisioning de tablas de control.
- Contexto dinámico priorizado desde
input/mapping.md. - Sampling de datos opcional con porcentaje configurable.
- Empaquetado como Databricks Asset Bundle.
- Dashboard con filtros cascading, 4 KPIs e historial.