Generar Descripciones Automáticas de Campos y SQL con Comentarios de una Base de Datos

En este artículo aprenderás cómo generar un diccionario de datos enriquecido a partir de tu base de datos, usando un modelo de lenguaje (por ejemplo, OpenFoundry o GPT) para describir cada campo, y cómo convertir esos resultados en sentencias SQL con comentarios listos para aplicar sobre tu esquema.

El proceso combina extracción de metadatos SQL, generación automática de descripciones, manejo de archivos parciales y exportación final de scripts.

Modelo utilizado para la prueba - OpenFoundry

---

🔍 1. Extracción de Metadatos desde la Base de Datos

Primero, necesitamos obtener la estructura de las tablas y columnas de nuestra base de datos (en este caso MySQL) en un formato JSON uniforme, como este:

{
  "Tabla": "app_cloud_billing",
  "Campo": "tags",
  "TipoDeDato": "JSON",
  "Restricciones": "NULL",
  "Descripcion": ""
}

Consulta SQL para extraer metadata de la base de datos

Puedes obtener esta información directamente desde INFORMATION_SCHEMA.COLUMNS:

SELECT 
    TABLE_NAME AS 'Tabla',
    COLUMN_NAME AS 'Campo',
    COLUMN_TYPE AS 'TipoDeDato',
    IS_NULLABLE AS 'Restricciones',
    COLUMN_COMMENT AS 'Descripcion'
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_SCHEMA = 'tu_base_de_datos'
ORDER BY TABLE_NAME, COLUMN_NAME;

Luego exportas el resultado en formato JSON (puedes hacerlo con una herramienta como DBeaver, MySQL Workbench o mediante un script Python).

---

🤖 2. Generación Automática de Descripciones con un Modelo de Lenguaje

Una vez tengas el archivo metadata_database.json, puedes usar un modelo como OpenFoundry, GPT u otro para generar descripciones automáticas.
El modelo recibirá algo como esto:

[
  {"Tabla": "app_cloud_billing", "Campo": "tags", "TipoDeDato": "JSON", "Restricciones": "NULL", "Descripcion": ""}
]

Y devolverá:

[
  {"Tabla": "app_cloud_billing", "Campo": "tags", "TipoDeDato": "JSON", "Restricciones": "NULL",
   "Descripcion": "Metadatos de facturación y atribución en formato JSON. Contiene etiquetas de clave/valor (ej. ambiente, proyecto, dueño) aplicadas al recurso"}
]

Para manejar grandes volúmenes de datos (más de 800 tokens), puedes dividir el archivo en bloques parciales y procesarlos por separado.

---

🧩 3. Guardar Resultados Parciales con Python

Usa este script para guardar los registros procesados en archivos parciales con timestamp:

import json
from datetime import datetime
import os

with open("campos.json", "r", encoding="utf-8") as f:
    campos = json.load(f)

campos_con_datos = [c for c in campos if c.get("Descripcion")]

os.makedirs("parciales", exist_ok=True)
timestamp = datetime.now().strftime("%Y-%m-%d-%H-%M")
output_path = f"parciales/diccionario_con_datos_{timestamp}.json"

with open(output_path, "w", encoding="utf-8") as f:
    json.dump(campos_con_datos, f, ensure_ascii=False, indent=2)

print(f"Archivo parcial generado en: {output_path}")

💡 Esto facilita retomar el proceso si el modelo falla o se interrumpe.
Cada archivo parcial queda versionado por hora y minuto.

---

🧮 4. Unificar Archivos Parciales

Si has generado varios archivos parciales, puedes consolidarlos en un solo archivo ordenado por tabla y campo:

import json
import os

carpeta_parciales = "parciales"
archivos_json = [f for f in os.listdir(carpeta_parciales) if f.endswith(".json")]

datos_unificados = []

for archivo in archivos_json:
    with open(os.path.join(carpeta_parciales, archivo), "r", encoding="utf-8") as f:
        datos_unificados.extend(json.load(f))

# Eliminar duplicados y ordenar
diccionario_unificado = {(d["Tabla"], d["Campo"]): d for d in datos_unificados}
ordenado = sorted(diccionario_unificado.values(), key=lambda x: (x["Tabla"], x["Campo"]))

with open("resultado_final.json", "w", encoding="utf-8") as f:
    json.dump(ordenado, f, ensure_ascii=False, indent=2)

print(f"Archivo unificado generado: resultado_final.json")

---

🧱 5. Generar Scripts SQL con Comentarios

Por último, puedes crear automáticamente los comandos SQL ALTER TABLE que agregan comentarios descriptivos a tus columnas.

Este script genera tanto un archivo SQL completo como archivos parciales por tabla:

import json
import os
from datetime import datetime

with open("resultado_final.json", "r", encoding="utf-8") as f:
    datos = json.load(f)

sql_por_tabla = {}
for item in datos:
    tabla = item["Tabla"]
    campo = item["Campo"]
    tipo = item["TipoDeDato"]
    restr = item["Restricciones"]
    desc = item["Descripcion"].replace("'", "''")  # escapar comillas simples

    sentencia = f"MODIFY COLUMN {campo} {tipo} {restr} COMMENT '{desc}'"
    sql_por_tabla.setdefault(tabla, []).append(sentencia)

os.makedirs("parciales_sql", exist_ok=True)
timestamp = datetime.now().strftime("%Y-%m-%d-%H-%M")

sql_total = ""

for tabla, sentencias in sql_por_tabla.items():
    bloque = f"ALTER TABLE {tabla}\n  " + ",\n  ".join(sentencias) + ";\n\n"
    sql_total += bloque

    with open(f"parciales_sql/{tabla}_{timestamp}.sql", "w", encoding="utf-8") as f:
        f.write(bloque)

with open(f"diccionario_sql_{timestamp}.sql", "w", encoding="utf-8") as f:
    f.write(sql_total)

print("✅ Archivos SQL generados en 'parciales_sql' y uno unificado.")

---

🧾 6. Ejemplo de Salida Final

Archivo diccionario_sql_2025-10-31-15-30.sql:

ALTER TABLE app_cloud_billing
  MODIFY COLUMN resourceName VARCHAR(512) NULL 
    COMMENT 'Nombre único y local del recurso de Azure',
  MODIFY COLUMN tags JSON NULL 
    COMMENT 'Metadatos de facturación y atribución en formato JSON. Contiene etiquetas de clave/valor (ej. ambiente, proyecto, dueño) aplicadas al recurso';

Archivos parciales (por tabla):

📁 parciales_sql/
 ┣ 📄 app_cloud_billing_2025-10-31-15-30.sql
 ┣ 📄 app_cloud_usage_2025-10-31-15-30.sql
 ┗ 📄 app_cloud_account_2025-10-31-15-30.sql

---

⚙️ 7. Requerimientos Python

Archivo requirements.txt mínimo:

openai
pandas

Si no usas OpenAI directamente, sustituye por el SDK del modelo que utilices (por ejemplo openfoundry).

---

🚀 Conclusión

Este proceso te permite:

• Documentar automáticamente la metadata de tu base de datos.

• Generar descripciones contextuales y consistentes usando IA.

• Mantener tus diccionarios actualizados con control de versiones.

• Aplicar los comentarios directamente en tu esquema SQL.

Es una solución práctica para equipos que manejan muchos modelos de datos y necesitan mantener la documentación sincronizada con el esquema técnico.