Um conjunto de contexto é uma coleção de informações específicas do banco de dados que permite que ferramentas como o QueryData gerem consultas com alta precisão. O conjunto de contexto inclui modelos, aspectos e pesquisas de valor que ajudam o QueryData a entender o esquema do banco de dados e a lógica de negócios dos seus aplicativos.
Há suporte para os seguintes bancos de dados:
- AlloyDB para PostgreSQL
- Cloud SQL para MySQL
- Cloud SQL para PostgreSQL
- Spanner
O que são conjuntos de contexto
Para criar aplicativos de agente eficazes, ferramentas como QueryData precisam entender sua organização de dados e lógica de negócios. Você fornece essas informações na forma de um conjunto de contexto.
Você define o contexto em arquivos que contêm objetos JSON para cada tipo de contexto. Você cria esses arquivos de contexto com a ajuda da CLI do Gemini. Em seguida, faça upload do arquivo de contexto para um conjunto de contexto criado no console do Google Cloud. Esse processo permite que ferramentas como QueryData aprendam o esquema específico do banco de dados e a lógica de negócios do aplicativo.
O arquivo de contexto é semelhante a este:
{
"templates": [
{
"nl_query": "Count Prague loan accounts",
"sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
"intent": "How many accounts associated with loans are located in the Prague region?",
"manifest": "How many accounts associated with loans are located in a given city?",
"parameterized": {
"parameterized_intent": "How many accounts associated with loans are located in $1",
"parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
}
}
],
"facets": [
{
"sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
"intent": "Average salary between 6000 and 10000",
"manifest": "Average salary between a given number and a given number",
"parameterized": {
"parameterized_intent": "Average salary between $1 and $2",
"parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
}
}
],
"value_searches": [
{
"query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
"concept_type": "Account Type",
"description": "Exact match for account types"
}
]
}
Formato do arquivo do conjunto de contexto
O arquivo de conjunto de contexto consiste em um conjunto selecionado de modelos e aspectos no formato JSON que orientam ferramentas como QueryData na tradução de perguntas em linguagem natural para consultas de um banco de dados específico. Definir o contexto garante a geração de SQL de alta precisão para padrões de consulta comuns.
Verifique se o conjunto de contexto é preciso e abrangente na cobertura de consultas esperadas do aplicativo para maximizar a acurácia.
Os conjuntos de contexto podem ser criados nas regiões us-central1, us-east1, europe-west4 e asia-southeast1.
Modelos de consulta
Os modelos de consulta são um conjunto selecionado de perguntas representativas em linguagem natural com consultas SQL correspondentes. Elas também incluem explicações para fornecer uma lógica declarativa para a geração de linguagem natural para SQL.
Um objeto de modelo de consulta é semelhante a este:
{
"templates": [
{
"nl_query": "Count prague loan accounts",
"sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
"intent": "How many accounts associated with loans are located in the Prague region?",
"manifest": "How many accounts associated with loans are located in a given city?",
"parameterized": {
"parameterized_intent": "How many accounts associated with loans are located in $1",
"parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
}
}
]
},
...
Os principais componentes do objeto JSON do modelo de consulta são:
nl_query: um exemplo de consulta em linguagem natural que ferramentas como QueryData processam.sql: a consulta SQL para a consulta em linguagem natural.intent: o objetivo ou o propósito da consulta em linguagem natural. Se não for definido, o valor padrão será a consulta em linguagem natural.manifest: uma forma generalizada e gerada automaticamente da intent.parameterized_intent: um formulário da intent com modelo e gerado automaticamente, com valores de entidade substituídos por parâmetros.parameterized_sql: um formulário com modelo e gerado automaticamente da consulta SQL que corresponde à intenção parametrizada.
Refinamentos de consulta
Os aspectos da consulta são um conjunto selecionado de condições representativas de linguagem natural com predicados SQL correspondentes. Os atributos gerenciam a filtragem e as condições, o que permite que os modelos de consulta realizem pesquisas facetadas.
Um objeto de atributo de consulta é semelhante a este:
{
...
"facets": [
{
"sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
"intent": "Average salary between 6000 and 10000",
"manifest": "Average salary between a given number and a given number",
"parameterized": {
"parameterized_intent": "Average salary between $1 and $2",
"parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
}
}
]
}
Os principais componentes do objeto JSON de atributo são:
sql_snippet: um snippet SQL. Para evitar ambiguidade, qualifique os nomes de coluna com nomes de tabela (por exemplo,table_name.column_name).intent: uma explicação do predicado SQL.manifest: uma forma generalizada e gerada automaticamente da intent.parameterized_intent: um formulário da intent com modelo e gerado automaticamente, com valores de entidade substituídos por parâmetros.parameterized_sql_snippet: um formulário com modelo e gerado automaticamente do sql_snippet que corresponde à intent parametrizada.
Consultas de pesquisa de valor
As consultas de pesquisa de valor são definidas pelo desenvolvedor e usam funções de correspondência para encontrar valores e o contexto deles em um banco de dados. A vinculação de valores usa os resultados dessas consultas para identificar quais tabelas e colunas contêm um valor correspondente, entender o tipo de conceito do valor e corrigir erros de ortografia.
A API QueryData usa a vinculação de valores para converter a linguagem natural em SQL com mais precisão. Ao usar consultas de pesquisa de valor, a API pode corrigir erros de ortografia e resolver tipos de valor com base nos valores do banco de dados, melhorando a precisão da conversão.
A vinculação de valores melhora a precisão da conversão de linguagem natural em SQL. Por exemplo, se um usuário perguntar: "Há voos saindo de Heathrow?", o banco de dados poderá armazenar o nome do aeroporto como "London Heathrow". Sem a vinculação de valores, o SQL gerado pode filtrar por WHERE name = 'Heathrow' e não retornar resultados. As consultas de pesquisa de valor orientam o agente a mapear "Heathrow" para o valor correto do banco de dados "London Heathrow" e o local do esquema (airports.name), garantindo que o SQL gerado seja preciso.
Um exemplo de consulta de pesquisa de valor é:
{
...
"value_searches": [
{
"query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
"concept_type": "Airport IATA Code",
"description": "Exact match (Standard SQL) for 3-letter airport codes"
},
{
"query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
"concept_type": "Airport Name",
"description": "Fuzzy match using standard trigram for partial airport names"
},
{
"query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
"concept_type": "Airport City",
"description": "Semantic search on string values for airport city names"
}
]
}
Os principais componentes do objeto JSON de pesquisa de valor são:
query: uma instrução SQL parametrizada que define a lógica para corresponder uma frase de valor aos valores armazenados em uma coluna de uma tabela em um banco de dados. O conjunto de resultados geralmente projeta o valor correspondente, o local do esquema, o tipo de conceito e uma métrica de distância normalizada (entre 0 e 1).concept_type: um rótulo semântico atribuído ao valor, por exemplo, odistrictou oloan_status. Esse rótulo ajuda a vincular valores e, eventualmente, ferramentas como a API QueryData a entender a função da frase de valor no esquema. Ele também ajuda a produzir uma instrução SQL que segmenta o conceito do valor, bem como a tabela e a coluna em que a frase de valor aparece.description: uma descrição da lógica de pesquisa.
Limitações
Os conjuntos de contexto têm as seguintes limitações:
- O Cloud SQL para SQL Server não é compatível.
- Os conjuntos de contexto para bancos de dados só são compatíveis com modelos, facetas e pesquisas de valor.
- Os conjuntos de contexto para bancos de dados são usados apenas pelo endpoint
QueryDatana API Análises de conversação.