Agente IA sobre datos estructurados: text-to-SQL con Gemini + BigQuery en la práctica

La mitad de las preguntas que los ejecutivos hacen al "ChatGPT de la empresa" son analíticas: comparaciones, totales, tendencias, segmentación. Sin text-to-SQL, el agente responde "consulte el BI". Con un text-to-SQL bien construido, el agente devuelve el número correcto con un gráfico.

Arquitectura estándar (7 pasos)

El componente clave: la capa semántica

El modelo no memoriza el esquema de tu data warehouse. Sin una capa semántica, adivina los nombres de tablas y columnas.

La capa semántica es un catálogo curado:

• Tablas y columnas con descripciones en PT/EN.
• Sinónimos ("receita" = "revenue" = "faturamento").
• Relaciones entre tablas (claves foráneas explícitas).
• Métricas predefinidas ("ticket promedio = SUM(valor)/COUNT(pedido)").
• Filtros predeterminados ("solo pedidos confirmados").
• Granularidad temporal y geográfica.

Herramientas: dbt + Looker semantic layer, Cube.js, o tu propia definición YAML. En proyectos Autenticare, estandarizamos en YAML versionado.

Patrones de prompt para text-to-SQL

Incluye siempre en el prompt:

• Esquema de las tablas relevantes (DDL completo).
• 3–5 ejemplos de pregunta → SQL bien formado.
• Dialecto explícito ("PostgreSQL 15", "BigQuery Standard SQL").
• Restricciones: "usa siempre LIMIT 1000", "nunca DELETE/UPDATE/DROP", "usa parámetros nombrados".
• Formato de salida: SQL puro entre code fence, sin comentarios extra.
• Regla de incertidumbre: "si no hay datos para responder, devuelve null + explicación".

Consulta patrones más amplios en prompt engineering corporativo.

Validación obligatoria antes de ejecutar

1. Parser SQL: garantiza que es SQL válido (no un comentario, no texto suelto).
2. Lista blanca de operaciones: solo SELECT.
3. Lista blanca de tablas: el agente solo puede tocar tablas marcadas como "agent-accessible".
4. Verificación de ACL: ¿el usuario tiene permiso en la tabla?
5. Dry run en BigQuery (costo cero, valida sintaxis y estima bytes).
6. Límite de bytes procesados (techo de costo).
7. Timeout de ejecución.

Patrón de "agente analítico" híbrido

En casos reales, es mejor combinar:

• Métricas predefinidas (capa semántica): para preguntas comunes, ejecuta una consulta lista con parámetros. Más rápido y más confiable.
• Text-to-SQL libre: para preguntas ad-hoc fuera del catálogo. Validación extra.
• RAG sobre diccionario: el agente consulta documentación de negocio (políticas, definiciones) antes de generar SQL.

Qué falla en un text-to-SQL ingenuo

Joins olvidados

"¿Cuánto vendimos por región?" — el agente olvida el JOIN con la tabla de tienda y devuelve un número incorrecto. Solución: joins recomendados en la capa semántica.

Filtros no declarados

"Facturación mensual" — el agente no filtra status="confirmado". Incluir siempre el filtro predeterminado en la capa semántica.

Granularidad temporal

"Ventas de marzo" — ¿marzo de qué año? Sin contexto, el agente asume incorrectamente. Incluye la fecha actual en el prompt + regla: "si el año no está especificado, usar el año en curso".

Conversión de moneda

Multinacional con BRL, USD, ARS en la misma tabla: el agente suma todo sin convertir. Una métrica derivada en la capa semántica lo resuelve.

Confusión entre métricas similares

"Ingresos netos" vs. "ingresos brutos" vs. "GMV" — sin una definición clara, el agente elige mal. Un glosario con definición canónica lo resuelve.

Evaluación específica

El gold set para text-to-SQL difiere del de RAG. Estructura:

• Pregunta en lenguaje natural.
• SQL esperado (canónico) o conjunto de SQLs equivalentes.
• Resultado esperado (números).
• Métrica primaria: execution match (el resultado coincide, aunque el SQL esté escrito diferente).
• Métrica secundaria: logical form match (estructura SQL correcta).

Un recall de 90%+ en execution match es un objetivo realista para un corpus de 100–300 preguntas. Detalles en evaluación de agentes en producción.

Costos a controlar

• Bytes BigQuery: límite por consulta y por usuario/día.
• Tokens Gemini: un esquema grande en el prompt consume tokens. Selecciona solo las tablas relevantes mediante una primera llamada (router).
• Caché de consultas: pregunta idéntica en una ventana corta = resultado en caché, sin re-ejecutar.

Gobernanza

• Audit log: pregunta + SQL generado + bytes procesados + resultado + usuario.
• Identidad real: la consulta se ejecuta con el permiso del usuario, no de una cuenta de servicio.
• Manejo de PII: nunca exponer CPF/e-mail en una respuesta agregada — la agregación es obligatoria en columnas sensibles.
• DPIA para análisis sobre datos personales — consulta DPIA para proyectos Gemini Enterprise.

Cuándo NO usar text-to-SQL

• Preguntas que requieren juicio ("¿qué deberíamos hacer?"): combinar con análisis complementario.
• Decisiones críticas (precio, oferta a cliente): el agente sugiere, el humano decide.
• Análisis complejos multi-tabla con lógica de negocio profunda: mejor BI tradicional + agente para resumir.

El text-to-SQL funciona cuando el agente sabe lo que no puede tocar. Capa semántica curada + lista blanca + dry-run >> prompt gigante con 200 tablas lanzadas adentro.