Cuando los nombres de las columnas engañan: cómo incorporar catálogos externos a NL2SQL++

El problema

NL2SQL++ (lenguaje natural a SQL++) es tan bueno como el conocimiento del esquema que lo respalda. Dele a un modelo de lenguaje grande (LLM) una pregunta como “¿Cuántos clientes con una solicitud previa activa cayeron en incumplimiento?” y tiene que saber qué tablas existen, qué significa cada columna y cómo se relacionan las tablas. La mayoría de los sistemas resuelven esto mediante incrustar el esquema de forma fija en el mensaje. Eso se rompe en el momento en que cambia el esquema, y colapsa por completo cuando los nombres de las columnas no tienen significado por sí mismos, la norma en los datos empresariales reales.

Considera las columnas a las que un modelo realmente se enfrenta en un esquema de producción. Algunos nombres son simplemente opacos: CUST_VAL_04 es el nivel de ingresos de por vida de un cliente, pero el nombre no dice nada sobre lo que contiene. Otros son peores que opacos, porque engañan: CLOSE_DT suena como una fecha de cierre de cuenta, sin embargo, almacena una código de estado (0 = abierto, 1 = congelado, 2 = cerrado) – un modelo que lo filtra como una fecha generará silenciosamente un SQL++ erróneo. Y luego están los casi duplicados que un nombre por sí solo no puede separar: BAL_CUR, BAL_AVG_30 y BAL_AVG_90 parecen “saldo”, pero solo uno es el actual saldo mientras que los otros son promedios de 30 y 90 días. Preguntar “¿Cuál es el saldo actual del cliente?” y solo de la columna descripción –no su nombre– revela que BAL_CUR es la correcta y las otras dos son trampas. Un analista humano recurre a un diccionario de datos para leer columnas como estas. Un LLM necesita lo mismo.

Ese diccionario ya existe dentro de la mayoría de las organizaciones, curado en catálogos de datos como DataHub y OpenMetadata: descripciones de columnas, tipos de datos y las relaciones de claves foráneas entre las tablas. El problema es que este conocimiento vive en un silo, desconectado de la base de datos operacional donde realmente se ejecutan las consultas.

Este proyecto conecta los catálogos de datos empresariales con Couchbase para que NL2SQL++ pueda leer lo que realmente significan las columnas en lugar de adivinarlo por sus nombres. Extrae los metadatos de las columnas de un catálogo, los incrusta en Couchbase y recupera el contexto correcto en el momento de la consulta mediante búsqueda vectorial, de modo que el esquema nunca está codificado de forma rígida. Y como diferentes clientes utilizan diferentes catálogos, la integración se basa en un patrón de proveedor conectableel cambio entre catálogos compatibles es un cambio de configuración, y admitir uno nuevo implica agregar un pequeño adaptador independiente, sin tocar el resto del sistema.

La Gran Idea: Una interfaz, cualquier catálogo

En el corazón de este diseño se encuentra un contrato único que implementa cada catálogo de datos. Cualquiera que sea la fuente, expone las mismas tres capacidades al resto de la tubería:

• Obtener metadatos de la columna – Cada columna de cada tabla dentro del alcance, cada una con su nombre, descripción, tipo de dato y ubicación completamente calificada.
• asociaciones de tipo fetch join – Las claves foráneas o los enlaces de linaje entre tablas, expresados como predicados de unión reutilizables.
• Transmitir cambios en vivo – Una fuente opcional de modificaciones al esquema, para que pueda mantener los metadatos actualizados sin necesidad de una recarga completa.

Una sola configuración selecciona qué catálogo está activo. Todo lo que está aguas abajo (el cargador, el motor de consultas, la sincronización en vivo) se comunica con este contrato común y nunca con un catálogo específico. Para admitir el siguiente catálogo (Atlan, un lago de datos S3 o algo aún no creado) se escribe un adaptador que cumple con el contrato; nada más cambia.

El conjunto de datos utilizado en todo momento es el público Datos de riesgo de incumplimiento de Home Credit desde Kaggle: siete tablas relacionadas (solicitudes de préstamos, registros del buró de crédito, solicitudes anteriores e historiales de saldos mensuales) conviviendo en Couchbase.
Cómo funciona, de principio a fin

Hay dos ciclos de vida. Uno único configuración carga los metadatos del catálogo en Couchbase y los hace aptos para búsquedas. El consulta flujo y luego responde preguntas sobre él. Un oyente en vivo opcional mantiene los metadatos actualizados a medida que el catálogo evoluciona.

Configuración: catálogo en Couchbase

La configuración se ejecuta en cuatro pasos, todos determinados por el catálogo que esté activo:

1. Obtener los metadatos de la columna y almacenar un registro por columna en Couchbase: su descripción, tipo de datos y ubicación.
2. Incruste la descripción de cada columna en un vector de 384 dimensiones utilizando un modelo sentence-transformer. Solo se incrusta la descripción, no el nombre críptico, y eso es lo que hace que una pregunta en lenguaje sencillo coincida con el significado de una columna en lugar de su etiqueta.
3. Construir un índice vectorial sobre esos embeddings (similitud de coseno) para que las búsquedas sean rápidas.
4. Obtener las relaciones de unión y guárdalos como un conjunto de predicados de unión deduplicados, por ejemplo: bureau.SK_ID_CURR = application_train.SK_ID_CURR.

Cada catálogo deriva esas uniones de su propio modelo nativo —DataHub a partir del linaje a nivel de columna, OpenMetadata a partir de restricciones de clave externa—, pero ambos producen las cadenas de predicado idénticas que el motor de consultas espera. Cabe destacar que el sistema no precalcula un grafo de unión rígido; conserva los predicados sin procesar y permite que el modelo en tiempo de consulta ensamble la ruta de unión válida mínima bajo demanda.

consulta a SQL++

Responder a una pregunta se realiza en tres etapas:

1. Comprender – La pregunta se divide en subconsultas enfocadas para que cada concepto pueda coincidir de forma independiente.
2. Recuperar – Cada subconsulta se incrusta y se ejecuta a través de una búsqueda vectorial sobre los metadatos de las columnas en Couchbase, conservando solo las coincidencias más cercanas por distancia de coseno. Aquí es donde EXT_SOURCE_2 emerge para una pregunta sobre puntajes de riesgo, puramente porque su descripción coincidencias – nunca su nombre.
3. Refinar – La búsqueda vectorial arroja una red amplia, por lo que un modelo de lenguaje reduce los candidatos a las columnas que realmente se necesitan para responder a la pregunta, inclinándose por conservar cualquier cosa útil.
4. Generar – Finalmente, la pregunta, las columnas elegidas y las relaciones de unión van a un modelo de Claude en AWS Bedrock, el cual está limitado a usar únicamente las uniones proporcionadas y el camino mínimo que conecta las tablas requeridas. El resultado es SQL++ ejecutable.

Debido a que las claves de combinación viajan por separado como predicados, el generador aún puede conectar combinaciones de múltiples tablas correctamente incluso cuando esas columnas de identificadores se eliminaron durante el refinamiento.

Mantenerse al día: sincronización de metadatos en vivo

Los catálogos cambian; por ejemplo, se renombran columnas, se corrigen descripciones y las tablas aparecen y desaparecen. Un escucha opcional de larga duración mantiene a Couchbase sincronizado sin volver a ejecutar la configuración. Cada catálogo observa su fuente de forma nativa —DataHub consume un flujo de eventos de registro de cambios, OpenMetadata sondea su extremo de eventos— y ambos traducen lo que ven en el mismos seis eventos de cambio normalizados. Un grupo de trabajadores compartidos aplica luego cada evento a los metadatos almacenados:

Cambiar	Qué pasa en Couchbase	¿Volver a integrar?
Nueva tabla agregada	Almacenar un registro para cada columna nueva	Sí
Columna agregada	Guardar la nueva columna	Sí
Descripción actualizada	Actualizar la descripción y es un vector	Sí
Tipo de dato cambiado	Actualizar solo el tipo	No
Columna eliminada	Elimina el registro de esa columna	No
Tabla eliminada	Elimina todos los registros de esa tabla	No

Ejecuciones de reincorporación de incrustaciones solo cuando el texto detrás del vector realmente cambia – una nueva columna o una descripción editada. Un cambio exclusivo de tipo de dato lo omite, por lo que no se recalcula nada sin motivo.
Por qué importa

Las pruebas en los datos de Home Credit confirmaron la tesis central: metadata-enhanced NL2SQL++ supera significativamente a un enfoque basado únicamente en el esquema. Frente a nombres de columnas opacos, proporcionar las descripciones del catálogo produjo SQL++ correcto; sin ellas, el modelo cometió errores sistemáticos en qué campos mapeaba y cómo filtraba.

El beneficio más amplio es arquitectónico. Al separar de dónde provienen los metadatos – el catálogo – de cómo se usa – incrustar, buscar, generar – cualquier cliente de Couchbase puede conectar su catálogo existente a la generación de consultas impulsada por IA y obtener resultados con conocimiento del esquema sin necesidad de mantener un esquema manualmente. El diseño conectable significa que el próximo catálogo es una adición pequeña y autónoma en lugar de una reescritura.

Dos ejemplos, uno al lado del otro

La brecha es más fácil de ver en SQL++. Ambas consultas a continuación son sintácticamente válido y se ejecuta limpiamente – la versión solo de esquema simplemente devuelve el respuesta incorrecta, porque el modelo adivinó el significado de una columna a partir de su nombre.

Ejemplo A – un valor que el nombre no puede revelar: ESTADO

“¿Cuántos registros mensuales del buró muestran un préstamo que fue dado de baja o con más de 120 días de atraso?”

STATUS en bureau_balance parece explicarse por sí solo, pero almacena un solo carácter códigos, etiquetas ilegibles. La descripción del catálogo detalla la codificación: “C significa cerrado, X significa estado desconocido, 0 significa sin DPD, 1 significa DPD máximo durante el mes entre 1 y 30, 2 significa DPD de 31 a 60, 5 significa DPD de 120+ o vendido o castigado.” “Castigado o con más de 120 días de atraso” es el código ‘5’, y no hay forma de saber eso por el nombre.

Sin el catálogo, el modelo inventa valores de cadena de texto de apariencia plausible que no coinciden con nada en los datos:

-- Sin catálogo: se ejecuta bien, devuelve 0 — las etiquetas adivinadas no existen
SELECT COUNT(*) AS num_records
FROM creditrisk.sampleScope.bureau_balance AS bb
WHERE bb.STATUS IN ['WRITTEN_OFF', 'DPD_120_PLUS', 'written_off'];

Con el catálogo, la codificación está en la descripción, por lo que se mapea al código real:

-- Con catálogo: correcto — '5' = DPD 120+ / vendido / castigado
SELECT COUNT(*) AS num_records
FROM creditrisk.sampleScope.bureau_balance AS bb
WHERE bb.STATUS = '5';

Ejemplo B – un sufijo que no significa nada por sí solo: SK_DPD vs SK_DPD_DEF

“¿Qué préstamos de POS/efectivo estuvieron vencidos durante un mes, ignorando las deudas triviales de bajo monto?”

Dos columnas casi idénticas se ubican una al lado de la otra en POS_CASH_balance. SK_DPD es “DPD (días de atraso) durante el mes del crédito anterior.” SK_DPD_DEF es “DPD durante el mes con tolerancia (se ignoran las deudas con montos de préstamo bajos).” La única pista es el sufijo _DEF, que no tiene significado por su nombre. “Ignorar deudas triviales de bajo monto” es precisamente SK_DPD_DEF, pero nada en el nombre lo indica.

Sin el catálogo, el modelo elige la columna con el nombre más simple y cuenta silenciosamente las deudas que la pregunta pedía excluir:

-- Sin catálogo: se ejecuta bien, pero SK_DPD NO ignora las deudas de bajo monto
SELECT pc.SK_ID_PREV,
       pc.MONTHS_BALANCE,
       pc.SK_DPD
FROM creditrisk.sampleScope.POS_CASH_balance AS pc
WHERE pc.SK_DPD > 0;

Con el catálogo, la cláusula de tolerancia en la descripción apunta a la columna derecha:

-- Con catálogo: correcto — SK_DPD_DEF aplica la tolerancia para montos bajos
SELECT pc.SK_ID_PREV,
       pc.MONTHS_BALANCE,
       pc.SK_DPD_DEF
FROM creditrisk.sampleScope.POS_CASH_balance AS pc
WHERE pc.SK_DPD_DEF > 0;

En ambos casos, el fallo es invisible a nivel de SQL: nada produce errores y nada parece extraño. Solo la columna descripción separa una consulta correcta de una con errores pero segura de sí misma.

Los metadatos enriquecidos ya existen en la empresa, este proyecto simplemente le enseña a la base de datos a entenderlos. ¿Tienes curiosidad por saber hacia dónde se dirige esto? Ponte en contacto con Couchbase para hablar sobre consultas conversacionales en tus datos.