Agente IA sobre datos estructurados: text-to-SQL con Gemini + BigQuery en la práctica
RAG maneja documentos. Pero ¿qué pasa con preguntas sobre datos estructurados en BigQuery, Snowflake o PostgreSQL? El patrón text-to-SQL con Gemini que realmente funciona — y lo que todavía requiere un humano.
Fabiano Brito
CEO & Founder
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)
Input bruto del usuario, con contexto de sesión.
El agente busca en el catálogo las tablas que cubren el tema (capa semántica).
Gemini 2.5 Pro produce una consulta parametrizada en el dialecto del warehouse.
Parser SQL + lista blanca de operaciones + ACL + dry-run.
BigQuery/Snowflake/Postgres con la identidad del usuario, no una cuenta de servicio.
El agente formatea el resultado y sugiere una visualización.
Número + tabla + gráfico opcional + la consulta utilizada (para auditoría).
| Aspecto | SQL Directo (Sin Capa Semántica) | Text-to-SQL + Capa Semántica |
|---|---|---|
| Precisión de nombres de columnas | Baja (el LLM alucina nombres) | Alta (mapeo estricto vía YAML) |
| Cálculo de métricas complejas | Inconsistente (ej. calcula mal el margen) | Garantizado (fórmulas predefinidas) |
| Seguridad de datos | Riesgosa (acceso directo a tablas) | Robusta (ACLs a nivel de usuario) |
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.
Abstracción de Negocio
Traduce la jerga técnica de la base de datos (ej. usr_sts_id = 4) a conceptos claros para el negocio ("usuarios activos").
Gobernanza Centralizada
Asegura que todas las interfaces (agentes, BI, reportes) utilicen exactamente las mismas definiciones de métricas.
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".
💡 Consejo de Producción
Implementa siempre un paso de dry-run en BigQuery antes de ejecutar la consulta real. Esto te permite validar la sintaxis de la consulta generada por Gemini y estimar el costo en bytes sin gastar recursos de procesamiento.
Preguntas Frecuentes
¿Cuál es la principal ventaja de usar text-to-SQL con Gemini y BigQuery?
Con text-to-SQL bien hecho, el agente retorna el número correcto con un gráfico, en lugar de solo indicar consultar el BI.
¿Cuáles son los pasos de la arquitectura estándar para text-to-SQL con Gemini y BigQuery?
La arquitectura estándar involucra 7 pasos, desde la pregunta en lenguaje natural hasta la respuesta auditable, incluyendo recuperación de schema, generación de SQL, validación, ejecución y post-procesamiento.
¿Por qué el 'semantic layer' es un componente clave en la arquitectura text-to-SQL?
Sin un 'semantic layer', el modelo puede adivinar nombres de tablas y columnas, comprometiendo la precisión de los resultados.
¿Qué es un 'semantic layer' en el contexto de text-to-SQL?
El 'semantic layer' es un catálogo curado que contiene tablas y columnas con descripciones, sinónimos, relaciones entre tablas, métricas pre-definidas, filtros estándar y granularidad temporal y geográfica.
¿Cuáles son los pasos de la arquitectura estándar para text-to-SQL con Gemini y BigQuery?
La arquitectura estándar involucra 7 pasos, desde la pregunta en lenguaje natural hasta la respuesta auditable, incluyendo recuperación de schema, generación de SQL, validación, ejecución y post-procesamiento.
¿Por qué el 'semantic layer' es un componente clave en la arquitectura text-to-SQL?
Sin un 'semantic layer', el modelo puede adivinar nombres de tablas y columnas, comprometiendo la precisión de los resultados.
¿Qué es un 'semantic layer' en el contexto de text-to-SQL?
El 'semantic layer' es un catálogo curado que contiene tablas y columnas con descripciones, sinónimos, relaciones entre tablas, métricas pre-definidas, filtros estándar y granularidad temporal y geográfica.
¿Listo para implementar Text-to-SQL en tu empresa?
Evita alucinaciones y protege tus datos con una arquitectura de producción diseñada por expertos.
Hablar con un especialista →