Visão geral do QueryData

Com o QueryData, é possível interagir com os dados do gráfico de propriedades no banco de dados do Spanner usando linguagem de conversação e criar agentes de dados. O QueryData gera consultas em linguagem GraphQL (GQL) com base em perguntas em linguagem natural, usando o esquema dos seus grafos de propriedades. Para melhorar a precisão dos seus casos de uso, você também pode fornecer conjuntos de contexto, uma coleção de modelos de consulta, facetas de consulta e pesquisas de valor que capturam sua lógica de negócios específica do domínio e as perguntas que seus usuários fazem. Para mais informações sobre conjuntos de contexto, consulte Visão geral dos conjuntos de contexto.

Quando usar QueryData

O QueryData para Spanner Graph é ideal para aplicativos como os seguintes:

  • Assistentes de conversação em dados de gráfico: um assistente de suporte ou analista responde à pergunta "Algum dinheiro enviado da conta 7 voltou para ela em até 60 dias?" fazendo com que o QueryData gere e execute a consulta GQL de vários saltos.
  • Copilotos de investigação para fraude, risco e compliance: os analistas exploram redes de propriedade e transferência por meio de perguntas de acompanhamento, enquanto um conjunto de contexto mantém termos como transferência de alto risco consistentes em todas as respostas.
  • Agentes de raciocínio do Mapa de Informações: os agentes criados com o ADK ou um cliente do MCP chamam QueryData como uma ferramenta para fundamentar o raciocínio nas relações armazenadas no gráfico, como as contas que uma pessoa controla por meio de intermediários.

Principais conceitos

Para traduzir de forma confiável perguntas de conversação em consultas GQL, o QueryData usa os seguintes conceitos principais:

QueryData e a API de Análise conversacional

O endpoint QueryData na API de Análise conversacional é uma ferramenta agêntica que permite a geração programática de consultas de linguagem natural para GQL (NL2GQL) para os gráficos de propriedades no seu banco de dados do Spanner. Em um aplicativo de conversação ou Agentic Workflows, o endpoint QueryData processa a interpretação do esquema e a síntese de consultas para os gráficos de propriedades que você lista no campo graph_ids de cada solicitação. A estrutura do agente (como Antigravity, Kit de Desenvolvimento de Agente (ADK) ou LangChain) gerencia o histórico de conversas, o estado do usuário e a orquestração de ferramentas para contextualizar a entrada do usuário antes de enviar uma solicitação em linguagem natural ao endpoint QueryData.

Conjuntos de contextos

Um conjunto de contexto é uma coleção de conhecimento específico do banco de dados, padrões de consulta selecionados e regras de negócios associadas ao seu banco de dados. Em vez de depender apenas do conhecimento geral do LLM ou do esquema de grafo de propriedades brutos, o QueryData usa conjuntos de contexto para entender as nuances do seu modelo de grafo e a terminologia específica da organização, como o que sua empresa considera uma transferência de alto risco em um grafo financeiro bancário. Os exemplos neste guia usam o esquema de gráfico de propriedades FinGraph e o conjunto de dados de amostra. Para criar o esquema FinGraph e inserir os dados de amostra, consulte Configurar e consultar o Spanner Graph.

Um conjunto de contexto contém três elementos básicos:

  • Modelos de consulta: pares selecionados de perguntas representativas em linguagem natural e as consultas GQL pré-validadas correspondentes. Os modelos fornecem exemplos canônicos que definem como as intenções de negócios específicas são mapeadas para as instruções GQL (por exemplo, como "Quais contas receberam transferências da conta de Dana?" é mapeada para uma consulta GRAPH FinGraph MATCH que atravessa as arestas Owns e Transfers).
  • Facetas de consulta: cláusulas GQL reutilizáveis (como padrões de gráfico, condições de filtro, períodos, limites de valor ou condições de negócios, como contas bloqueadas). As facetas permitem que o QueryData combine dinamicamente vários critérios de filtragem em uma consulta sem precisar de modelos separados para cada combinação.
  • Pesquisas de valor: consultas semânticas e de correspondência de strings, escritas como instruções SELECT em GRAPH_TABLE, que fundamentam frases de valor na pergunta de um usuário para os valores exatos armazenados nas propriedades de nó e aresta. As pesquisas de valor ajudam a resolver ambiguidades (por exemplo, mapear "dia chuvoso" para o apelido da conta Rainy Day Fund ou "República Tcheca" para o valor armazenado Czech_Republic) usando correspondências exatas, similaridade de strings ou embeddings de vetores semânticos.

Como o QueryData funciona

Quando seu agente ou aplicativo envia uma solicitação em linguagem natural (como uma pergunta do usuário que o agente contextualizou com o histórico de conversas ou o estado do usuário), o QueryData realiza as seguintes etapas:

  1. Resolução de valores: o QueryData executa consultas de pesquisa de valor no banco de dados do Spanner para mapear frases de valor no comando (como o nome de uma pessoa, o apelido de uma conta ou um país) para valores de propriedade de nó e aresta específicos.
  2. Correspondência de intent e desambiguação: o QueryData compara a solicitação contextualizada com os modelos de consulta e as facetas que você definiu no conjunto de contexto. Se a solicitação for pouco especificada ou ambígua, o QueryData poderá retornar uma pergunta de desambiguação para que o agente ou aplicativo possa pedir esclarecimentos ao usuário.
  3. Síntese de consulta: usando o esquema dos gráficos de propriedades listados em graph_ids, a estrutura do modelo correspondente, as facetas aplicadas e os valores resolvidos, o QueryData sintetiza uma consulta GQL completa.
  4. Execução da consulta: a consulta GQL gerada é executada no banco de dados do Spanner para retornar resultados.

Criar e gerenciar conjuntos de contexto

Para criar e gerenciar conjuntos de contexto, faça o seguinte:

  1. Contexto do autor: defina os modelos de consulta, as facetas e as pesquisas de valor para o gráfico de propriedades. Para mais informações, consulte Visão geral dos conjuntos de contexto. Também é possível usar o agente de engenharia de contexto para automatizar a criação de contexto.
  2. Gerenciar no console do Google Cloud : crie e gerencie conjuntos de contexto no Spanner Studio para disponibilizá-los para a geração de consultas.
  3. Integração com seus aplicativos: conecte seus aplicativos ou agentes de IA ao QueryData usando chamadas diretas da API REST, com os gráficos de propriedades de destino listados em graph_ids.

A seguir