Introdução ao QueryData

O QueryData é uma ferramenta de linguagem natural para SQL (NL2SQL) na API Conversational Analytics que permite que seus agentes de IA e aplicativos consultem bancos de dados operacionais usando linguagem natural. Quando um aplicativo ou agente envia uma pergunta usando linguagem natural, o QueryData a traduz em uma consulta SQL específica do dialeto, executa a consulta no banco de dados e retorna os resultados, além do SQL gerado e uma explicação de como o QueryData interpretou a pergunta.

Para mais informações sobre como usar o QueryData com seu banco de dados, consulte a documentação dos bancos de dados compatíveis:

Principais recursos

O QueryData oferece os seguintes recursos para aplicativos de banco de dados agênticos:

  • Alta precisão: alcance quase 100% de precisão em consultas essenciais para os negócios combinando metadados de esquema de banco de dados com conjuntos de contexto que você seleciona.
  • Relevância para os negócios: baseie a geração de SQL na terminologia de domínio, nas definições de métricas e na lógica de negócios da sua organização, em vez de depender apenas de nomes brutos de tabelas e colunas.
  • Explicabilidade: gere explicações de intent legíveis por humanos junto com a consulta SQL sintetizada e a resposta em linguagem natural para que você e seus usuários possam verificar como o QueryData traduziu uma solicitação.
  • Segurança de dados: aplique o controle de acesso no nível da linha e proteja os dados do usuário contra injeção de comandos usando visualizações seguras parametrizadas no AlloyDB, no Cloud SQL para MySQL e no Cloud SQL para PostgreSQL.

Quando usar o QueryData

O QueryData foi projetado para desenvolvedores que estão criando aplicativos interativos e agentes de IA que precisam de acesso rápido, previsível e preciso a dados de bancos de dados operacionais. Por exemplo, o QueryData é ideal para os seguintes casos de uso:

  • Automação do atendimento ao cliente: responda a um grande volume de consultas de usuários, como "Onde está meu pedido?" ou "Qual é o saldo atual da minha conta?"
  • Assistentes de pesquisa de e-commerce e catálogo: ajudam os usuários a filtrar e explorar catálogos estruturados com perguntas de vários critérios, como "Mostre-me laptops leves com pelo menos 16 GB de RAM e uma duração de bateria de mais de 10 horas".
  • Operações de campo e ferramentas internas: permita que os funcionários consultem níveis de inventário em tempo real, disponibilidade de peças ou status de tíquetes de serviço em tempo real.
  • Fluxos de trabalho multiagente: exponha consultas estruturadas de banco de dados como uma ferramenta em Agentic Workflows, como o Kit de Desenvolvimento de Agente (ADK), o MCP Toolbox for Databases ou o LangChain.

Como o QueryData funciona

Os modelos de linguagem grandes (LLMs) genéricos não têm informações sobre os valores de dados privados da sua organização, nomes de colunas enigmáticos ou regras de negócios específicas do domínio. Para preencher a lacuna entre como os usuários fazem perguntas e como o banco de dados armazena dados, o QueryData usa o seguinte contexto em camadas:

  • Ontologias de esquema: descrições enriquecidas de tabelas e colunas no catálogo do banco de dados ou no Knowledge Catalog que explicam o significado comercial de tabelas, colunas, códigos de status e relações de mesclagem.
  • Conjuntos de contexto: coleções selecionadas associadas à instância do banco de dados que definem os três elementos básicos a seguir:
    • Modelos de consulta: perguntas representativas em linguagem natural combinadas com instruções SQL parametrizadas e validadas e explicações de intent.
    • Facetas de consulta: predicados SQL modulares e fragmentos de filtro que o QueryData combina dinamicamente com modelos de consulta para oferecer suporte à pesquisa facetada sem exigir um modelo separado para cada combinação de filtro.
    • Pesquisas de valor: consultas de pesquisa exatas, de trigrama aproximado ou de vetor semântico que vinculam frases informais do usuário, sinônimos ou termos com erros de ortografia a valores e colunas reais no banco de dados.

Quando o aplicativo chama o método projects.locations.queryData na API Conversational Analytics, o QueryData executa as seguintes etapas:

  1. Resolução de valores: executa consultas de pesquisa de valor no banco de dados para mapear frases de entidade no comando (como nomes de cidades, categorias dos produtos ou códigos) para valores exatos de colunas do banco de dados.
  2. Correspondência e desambiguação de intent: compara a pergunta do usuário com os modelos de consulta e as facetas no conjunto de contexto, bem como com a ontologia do esquema. Se uma pergunta for ambígua ou não tiver os parâmetros necessários, o QueryData poderá retornar perguntas de desambiguação para esclarecer a intenção do usuário.
  3. Síntese de consulta: sintetiza uma consulta SQL específica do dialeto combinando a estrutura de modelo correspondente, as facetas aplicáveis e os valores literais resolvidos ou gerando SQL com base na ontologia do esquema quando nenhum modelo corresponde.
  4. Execução e resposta da consulta: executa o SQL gerado no banco de dados de destino e retorna o conjunto de resultados tabulares, a consulta SQL gerada, uma explicação da intent e um resumo opcional em linguagem natural.

Estratégias para alcançar quase 100% de precisão em texto para SQL

Alcançar quase 100% de acurácia na conversão de texto em SQL é um processo de engenharia iterativo conhecido como hill-climbing. Em vez de tentar antecipar todas as possíveis perguntas do usuário, comece com descrições de esquema de referência, avalie seu agente em relação a um comparativo de mercado representativo de consultas SQL de ouro usando o EvalBench e, em seguida, resolva as lacunas de precisão.

Para mais informações sobre estratégias recomendadas (ou receitas) para resolver lacunas de acurácia, incluindo diagramas de arquitetura, exemplos de SQL e comparativos de mercado de avaliação, consulte Seis receitas para alcançar quase 100% de acurácia na conversão de texto em SQL e teste o codelab complementar para aprender a implementar essas receitas de acurácia de conversão de texto em SQL.

Em resumo, as seis receitas são as seguintes:

  • Receita 0: inicializar um conjunto de contexto e conectar seu aplicativo. Comece com comentários descritivos de tabelas e colunas no esquema e conecte seu aplicativo ao QueryData usando as bibliotecas de cliente da API Conversational Analytics ou a ferramenta cloud-gemini-data-analytics-query no MCP Toolbox for Databases.
  • Receita 1: injetar interpretação com modelos de consulta. Forneça exemplos de consultas SQL validadas para suas perguntas de negócios mais importantes e generalize-as em modelos SQL parametrizados, explicações de intent parametrizadas e manifestos que capturem variantes de perguntas semanticamente equivalentes.
  • Receita 2: use modelos facetados. Combine modelos de consulta base com facetas de consulta modulares (condições SQL reutilizáveis com os próprios manifestos e intents) para que o QueryData possa compor dinamicamente consultas com vários filtros sem exigir um modelo separado para cada combinação de condições.
  • Receita 3: eliminar ambiguidade com a pesquisa de valor. Defina consultas de pesquisa de valor para vincular frases de valor em perguntas de linguagem natural, incluindo terminologia particular, sinônimos e erros de ortografia, a colunas e valores reais do banco de dados, e permita que o QueryData solicite esclarecimentos quando um termo corresponder a vários tipos de entidade.
  • Receita 4: integrar a pesquisa semântica e os operadores de IA. Combine modelos e facetas SQL estruturados com pesquisa vetorial e operadores de IA no banco de dados (como AI.IF e AI.RANK no AlloyDB) para filtrar e classificar texto não estruturado ou dados multimodais usando critérios semânticos.
  • Receita 5: use visualizações seguras parametrizadas. Aplique segurança rigorosa no nível da linha e proteja os dados do usuário contra injeção de comandos vinculando parâmetros de usuário autenticados em visualizações seguras parametrizadas para o AlloyDB, o Cloud SQL para MySQL e o Cloud SQL para PostgreSQL.

É possível aplicar essas receitas manualmente ou automatizar o fluxo de trabalho de escalonamento, expandindo conjuntos de avaliação, executando avaliações do EvalBench, analisando lacunas de precisão e propondo novos modelos, facetas e pesquisas de valor, usando o agente de engenharia de contexto de código aberto.

A seguir