Un conjunto de información contextual es el conocimiento del dominio que potencia
QueryData.
Define cómo funciona tu lógica empresarial antes de que tu aplicación se publique, de modo
que QueryData pueda responder preguntas en lenguaje natural con una exactitud cercana al 100% y una baja latencia en línea.
Si bien el contexto de dominio puede adoptar muchas formas, los conjuntos de contexto admiten tres tipos de contexto especializados:
- Plantillas de consultas: Consultas en SQL aprobadas previamente para preguntas empresariales comunes.
- Facetas de consulta: Son filtros modulares, como "starter family" o "ocean view", que se adjuntan de forma dinámica a las plantillas.
- Búsquedas de valores: Son búsquedas de entidades que asignan frases de usuario a valores exactos de la base de datos y resuelven la ambigüedad.
Se admiten las siguientes bases de datos:
- AlloyDB para PostgreSQL
- Cloud SQL para MySQL
- Cloud SQL para PostgreSQL
- Spanner
- Firestore compatible con MongoDB
- Bigtable
Qué son los conjuntos de contexto
Creas y optimizas conjuntos de contexto en el momento del diseño con el
agente de ingeniería de contexto.
El agente de ingeniería de contexto ejecuta una comparativa de referencia representativa a través de
QueryData, puntúa los resultados y define mejor de forma iterativa
(hill-climbs)
tu conjunto de contexto. Luego, verifica la versión final con un conjunto de pruebas de exclusión no visto para evitar el sobreajuste y sube automáticamente el conjunto de contexto aGoogle Cloud.
Vincular tu base de datos con un conjunto de contexto seleccionado ofrece dos beneficios principales para la producción:
- Precisión cercana al 100% que se generaliza: Los esquemas de bases de datos describen tablas y columnas, pero no pueden decirle a un modelo qué distancia se considera "cercana" o qué calificación hace que una escuela sea "buena". Los conjuntos de contexto fundamentan QueryData en las reglas empresariales verificadas de tu organización, mientras que los patrones parametrizados permiten que un conjunto de contexto compacto se generalice en variaciones de frases, combinaciones de filtros y valores de entidades.
- Ejecución rápida en línea y baja latencia: La ingeniería de contexto traslada el razonamiento de esquemas costoso sin conexión al tiempo de diseño:
- Ejecución con coincidencia de contexto con un conjunto de contexto: Ejecución rápida de un solo paso a través de la coincidencia de plantillas precompiladas y las búsquedas de valores indexados.
- Síntesis de zero-shot para consultas imprevistas sin plantillas: Tarda de 2 a 3 veces más porque el modelo debe explorar los metadatos del esquema y sintetizar SQL en el entorno de ejecución.
- Exploración abierta basada en agentes con herramientas de SQL sin procesar: Suele tardar más de 30 segundos debido a las consultas de prueba y error de varios turnos y a los bucles de corrección de errores.
Arquitectura de ubicación de contexto
Cuando prepares una base de datos para QueryData, coloca cada tipo de conocimiento del dominio en el nivel de contexto que coincida con su alcance y comportamiento de recuperación:
| Nivel | Mecanismos | Información que debes incluir | Límites funcionales |
|---|---|---|---|
| Nivel 1: Comentarios del catálogo de esquemas | Declaraciones COMMENT ON TABLE y COMMENT ON COLUMN de la base de datos (o descripciones de esquemas databaseTableReferences intercaladas) |
Significados concisos de las columnas, unidades de medición (como centavos en comparación con dólares o marcas de tiempo UTC), valores de enumeración cerrados (por ejemplo, 'PENDING', 'SETTLED', 'FAILED') y notas de baja |
Se inserta cada vez que la tabla está dentro del alcance. Mantén los comentarios concisos para que no inflen la instrucción del esquema. |
| Nivel 2: Contexto global de la instrucción | Instrucciones del agente organizador externo (incluidas en QueryData prompt) o DataAgent system_instruction |
Invariantes entre tablas, zonas horarias predeterminadas para los informes, filtros globales de borrado no definitivo (como deleted_at IS NULL), puentes de ID de entidades combinadas y fechas de migración de sistemas de eras históricas |
Se incluye en cada solicitud sin filtrado de recuperación de top-K. Sé conciso (menos de 1,500 tokens). |
| Nivel 3A: Plantillas de consultas | templates en el archivo JSON del conjunto de contexto |
De 8 a 25 uniones de varias tablas, agregaciones y backbones de nivel de detalle componibles con marcadores de posición de parámetros $1 y $2 |
Quita todos los comentarios -- y /* ... */ para que la compactación de JSON de una sola línea no marque como comentario el SQL final. Evita codificar de forma rígida los límites de las políticas condicionales en las plantillas generales. |
| Nivel 3B: Facetas de búsqueda | facets en el archivo JSON del conjunto de contexto |
Vocabulario del dominio, métricas con nombre y predicados de filtro de cohorte o política con alcance | Califica cada columna con el nombre de su tabla (table_name.column_name, nunca alias de tabla) y establece límites de aplicabilidad exactos en intent. |
| Nivel 4: Búsquedas de valor | value_searches en el archivo JSON del conjunto de contexto |
Resolución de entidades de cardinalidad alta, sinónimos o nombres propios parciales en tablas de consulta | Restringe a tablas de búsqueda o de dimensiones indexadas (menos de 100,000 filas) o vistas materializadas SELECT DISTINCT actualizadas con CTE ORDER BY ... LIMIT 10 interna. No lo uses para enumeraciones cerradas pequeñas ni tablas de hechos no indexadas. |
Tipos de contexto en un conjunto de contextos
En el entorno de ejecución, QueryData combina los tres tipos de contexto en un solo paso. Por
ejemplo, si un usuario pregunta lo siguiente:
"Búscame casas cerca de buenas escuelas en Del Mar para una familia que recién empieza, con vista al mar".
QueryData resuelve la solicitud en cuatro pasos coordinados:
- Una plantilla de consulta proporciona la estructura de consulta principal para "casas cerca de buenas
escuelas en
$1", aplicando reglas de negocio para la distancia (dentro de 3 kilómetros) y la clasificación de la escuela (5 o mejor). - Las facetas de consulta insertan filtros modulares para "casa para familia pequeña" (3 a 4 dormitorios, 2 o más baños) y "vista al mar" (búsqueda de similitud de vectores).
- Una búsqueda de valor encuentra
'Del Mar'en la columnacities.city_namey verifica su tipo de concepto. - Las explicaciones de intención se combinan en una explicación certificada que se devuelve junto con los resultados de la consulta: "Casas en Del Mar a menos de 3 kilómetros de escuelas con una calificación de 5 o más, con 3 a 4 dormitorios y vista al mar".
Plantillas de consulta
Las plantillas de consultas son un conjunto seleccionado de preguntas representativas en lenguaje natural con las consultas en SQL correspondientes. También incluyen explicaciones para proporcionar una justificación certificada de cómo se interpretó una pregunta.
Por ejemplo, si un usuario le pregunta a una aplicación de bienes raíces: "Encuéntrame casas cerca de buenas escuelas en Del Mar", el esquema de la base de datos por sí solo no define qué distancia se considera "cerca", qué calificación hace que una escuela sea "buena" o cómo clasificar las propiedades coincidentes. Una plantilla de consulta captura esa interpretación empresarial exacta, como las propiedades que se encuentran a menos de 3 kilómetros de una escuela con una clasificación de 5 o más, ordenadas por una puntuación ponderada de clasificación y proximidad, y la generaliza para cualquier ciudad.
Los componentes principales de una plantilla de consulta son los siguientes:
- Ejemplo de pregunta en lenguaje natural: Es una pregunta representativa que se hace en inglés simple, como "Encuentra casas cerca de buenas escuelas en Del Mar".
- Consulta en SQL de ejemplo: Es la consulta en SQL verificada que responde la pregunta según tus reglas empresariales.
- Patrón de pregunta generalizado: Es un patrón generado de forma automática con valores específicos reemplazados por descripciones genéricas, como "Encuentra casas cerca de buenas escuelas en una ciudad determinada", que se usa para hacer coincidir las preguntas entrantes con las variaciones de frases.
- Explicación de la intención: Es una explicación certificada y en lenguaje sencillo de las reglas empresariales que aplica la consulta, como "Buscar casas en
$1a menos de 3 kilómetros de una escuela con una clasificación de al menos 5". - Consulta en SQL parametrizada: Es la consulta en SQL ejecutable
que corresponde a la explicación de la intención, con parámetros como
$1.
- Quita los comentarios de SQL: Quita todos los comentarios de línea
--y los comentarios de bloque/* ... */desqlyparameterized_sql, en especial antes de compactar SQL de varias líneas en una sola línea de JSON en la que un comentario--marcaría como comentario el resto de la instrucción. - Mantén las plantillas enfocadas en las estructuras principales: Usa plantillas para capturar
patrones reutilizables de unión de varias tablas, nivel de detalle de agrupamiento y agregación
(por lo general, de 8 a 25 plantillas por conjunto de contexto). Coloca límites de políticas condicionales
o predicados
WHEREespecíficos de la cohorte en las facetas de consulta en lugar de codificarlos de forma fija en plantillas generales.
Facetas de consulta
Las facetas de consulta son un conjunto seleccionado de condiciones de lenguaje natural representativas con predicados de SQL correspondientes. Las facetas administran el filtrado y las condiciones, lo que permite que las plantillas de consulta realicen búsquedas por facetas sin necesidad de una plantilla independiente para cada combinación de filtros.
Por ejemplo, un usuario puede extender la consulta "Encuentra casas cerca de buenas escuelas en Del Mar" con condiciones adicionales:
- "...para una familia que recién empieza", que se asigna a un filtro de SQL estructurado,
como
properties.bedrooms BETWEEN 3 AND 4 AND properties.bathrooms >= 2.0. - "...with an ocean view," que
usa operadores de IA de bases de datos, como
ai.if, o la búsqueda de similitud de vectores (<=>) en columnas no estructuradas, comolisting_description,listing_image_embeddingsycustomer_reviews.
Los componentes principales de una faceta de consulta son los siguientes:
- Fragmento de SQL: Es la condición de filtro de SQL reutilizable, como
properties.bedrooms BETWEEN 3 AND 4 AND properties.bathrooms >= 2.0. Para evitar ambigüedades, califica cada nombre de columna con su nombre de tabla completo, por ejemplo,table_name.column_name. No uses nombres de columnas simples ni alias de tablas, comot1.column_name. - Patrón de condición generalizado: Es el patrón de lenguaje natural con el que coincide la faceta, como "Adecuado para una familia que recién comienza".
- Explicación de la intención: Es una explicación certificada de la condición del filtro, que se devuelve como parte del fundamento general de la respuesta, incluidos sus límites de aplicabilidad exactos (por ejemplo, a qué cohorte de entidad, estado o período se aplica la condición).
- Fragmento de SQL parametrizado: Es el fragmento de SQL ejecutable que corresponde a la explicación de la intención.
Búsquedas de valor
Las búsquedas de valores
son consultas definidas por el desarrollador que usan funciones de coincidencia, como la coincidencia exacta,
la similitud de trigramas difusos o la búsqueda de vectores semánticos, para encontrar valores y su
contexto dentro de una base de datos. QueryData usa la vinculación de valores en estos resultados para
identificar qué
tablas y columnas
contienen un valor coincidente, comprender el tipo de concepto del valor, corregir
errores ortográficos y detectar ambigüedades antes de ejecutar SQL.
Por ejemplo, si un usuario le pide a una aplicación de bienes raíces las "propiedades vendidas de Westwod
en el último mes", un modelo solo de esquema podría filtrar por
`WHERE name = 'Westwod'`
y no devolver resultados. Las consultas de búsqueda de valores usan la coincidencia aproximada para resolver el
error ortográfico "Westwod" en el valor de la base de datos 'Westwood'. Además, si 'Westwood' existe en varios tipos de conceptos de la base de datos, como City, Municipality y Brokerage, la vinculación de valores detecta la ambigüedad para que QueryData pueda pedirle al usuario que aclare a qué concepto se refiere en lugar de adivinarlo.
Los componentes principales de una consulta de búsqueda de valores son los siguientes:
- Consulta de búsqueda: Es una consulta en SQL parametrizada que usa
coincidencia exacta, similitud de trigramas (
pg_trgm) o Vector Search para encontrar un valor dentro de una columna. - Tipo de concepto: Es una etiqueta semántica, como
City,MunicipalityoBrokerage, que especifica lo que representa el valor y en qué columna se debe filtrar. - Descripción: Una breve descripción de la lógica de búsqueda.
Cuando diseñes
value_searchespara bases de datos SQL, sigue estas reglas para evitar fallas en las consultas en el entorno de ejecución y análisis de tablas con alta latencia:- Coloca
ORDER BYyLIMITdentro de una CTE o subconsulta, nunca en el nivel superior: En el entorno de ejecución,QueryDatapuede combinar varias consultasvalue_searchesconUNION ALL. Para asegurarte de que cada consulta limite su propio análisis de índice, colocaORDER BY ... LIMIT 10dentro de una expresión de tabla común (CTE)WITHo una subconsulta derivada, en lugar de hacerlo en el nivel superior. - Consulta tablas de búsqueda indexadas, nunca tablas de hechos grandes ni enumeraciones cerradas: Ejecuta búsquedas de valores solo en tablas de búsqueda o de dimensiones pequeñas (menos de 100,000 filas) respaldadas por un índice de trigrama o de vectores, o en una vista materializada
SELECT DISTINCTactualizada extraída de una tabla más grande. Nunca ejecutesvalue_searchesdirectamente en tablas de hechos o registros con millones de filas, nunca calcules incorporaciones intercaladas por fila en columnas de tablas en el momento de la consulta y omitevalue_searchespara enumeraciones cerradas pequeñas (en su lugar, documenta los valores de enumeración cerrados en los comentarios de las columnas).
¿Qué sigue?
- Aprende a crear conjuntos de información contextual con el agente de ingeniería de contexto.
- Obtén más información para crear o borrar un conjunto de contexto en AlloyDB Studio.
- Coloca