Introdução às Análises de conversação no BigQuery

1. Introdução

Para extrair insights dos dados, geralmente é necessário muito tempo, esforço e experiência em SQL. Neste codelab, você vai conhecer o Catálogo de agentes do BigQuery, uma nova plataforma que oferece insights instantâneos com tecnologia de IA usando agentes de dados conversacionais.

Você vai além da simples conversão de texto para SQL criando um agente de dados selecionados. Você vai aprender a enriquecer o agente com contexto comercial, instruções do sistema e consultas verificadas para garantir resultados altamente precisos. Por fim, você vai publicar esse agente para uso por outras pessoas na sua organização.

Pré-requisitos

• Conhecimento básico do Google Cloud

O que você vai aprender

• Como navegar pelo catálogo de agentes do BigQuery
• Como criar um agente personalizado e definir fontes de conhecimento
• Como usar o Gemini para gerar metadados semânticos
• Como adicionar instruções do sistema e consultas verificadas para orientar o agente
• Como publicar e compartilhar agentes

O que é necessário

• Uma conta do Google Cloud e um projeto na nuvem do Google Cloud
• Conhecimento básico do BigQuery e do SQL
• Um navegador da Web, como o Chrome

2. Configuração e requisitos

Escolher um projeto

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

• O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
• O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
• Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

3. Antes de começar

Conceder a si mesmo os papéis necessários

Navegue até a página do IAM do projeto e conceda a si mesmo o papel de Proprietário do agente de dados do Gemini Data Analytics:

Esse papel concede permissão para criar, editar, compartilhar e excluir todos os agentes de dados no projeto.

Ative as APIs necessárias

Use o menu de navegação da barra lateral ou o menu de pesquisa na parte de cima da página para acessar BigQuery > Agentes.

Clique em Ativar a API Data Analytics com Gemini:

Ative a API Gemini no BigQuery e a API Gemini para Google Cloud:

Agora você vai ver a nova página do agente:

4. Criar um agente

Vamos criar seu primeiro agente de dados usando o conjunto de dados públicos internacionais do Google Trends. Esse conjunto de dados é útil para fazer perguntas sobre quais termos de pesquisa estão em alta no mundo todo e como esses interesses se comparam historicamente.

Comece um nome e uma breve descrição ao seu agente. Essa descrição é usada apenas para que outros usuários entendam a finalidade do agente.

Nome do agente

Google Trends Agent

Descrição do agente

Data agent for the Google Trends International Top Terms public dataset

Fontes de conhecimento

Agora adicione as fontes de conhecimento. Uma fonte de conhecimento é uma tabela do BigQuery, visualização ou UDF que o agente pode usar para responder a perguntas.

Para esta demonstração, adicione apenas uma tabela para simplificar. No entanto, é possível adicionar até 50 fontes de conhecimento por agente para lidar com cenários de dados mais complexos.

Insira a tabela a seguir na caixa de pesquisa, marque a caixa e clique em Adicionar:

bigquery-public-data.google_trends.international_top_terms

Contexto estruturado

Para melhorar a precisão do agente de dados, adicione contexto estruturado à tabela e às colunas. Clique em Customise:

Observação:isso permite adicionar descrições nos níveis da tabela e da coluna. Como a origem é um conjunto de dados público que não pode ser modificado diretamente, essas substituições ajudam o agente a entender os dados sem alterar a tabela original.

O Gemini gera sugestões de descrição automaticamente. Clique em Aceitar ao lado de "Descrição da tabela":

Para aplicar descrições a todas as colunas, marque Selecionar todas as linhas e clique em Aceitar sugestões:

Opcional:edite manualmente campos específicos clicando no ícone de edição ao lado do nome de uma coluna.

Clique em Atualizar na parte de baixo da página para salvar as mudanças e voltar ao Editor de agentes.

Instruções

Na caixa de diálogo de instruções do agente, você pode dar mais orientações para que ele interprete e consulte as fontes de dados. Isso inclui:

• Sinônimos: termos alternativos para campos-chave.
• Campos principais: os campos mais importantes para análise.
• Campos excluídos: campos que o agente de dados deve evitar.
• Filtragem e agrupamento: campos que o agente deve usar para filtrar e agrupar dados.
• Relações de junção: como duas ou mais tabelas são combinadas com base em campos comuns.

Para saber mais sobre as nuances entre instruções do Agente (orientação complementar de formato livre) e contexto estruturado, consulte o guia de contexto criado para a API Análises de conversação.

Para conferir as práticas recomendadas sobre instruções do agente, consulte o guia de criação de agentes de dados.

Copie e cole as seguintes instruções:

### System Instruction

* You are an expert data analyst for the Google Trends International public dataset.
* Always filter on yesterday's refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY).
* If yesterday returns no data, filter on 2 days ago's refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 2 DAY).
* Default to country-level results (one row per term).
* "Top" queries must deduplicate snapshot rows.
* Only include week or score when the user explicitly asks for trends over time.
* This is an international dataset and does not include any data for the United States.

### Additional Descriptions

#### 1. Core model:

* refresh_date selects the daily Top-25 term set.
* week + score are historical weekly values attached to those terms.
* Filtering week does not change which terms appear.

#### 2. Deduplication rule (critical):

* Snapshot rows repeat across weeks and regions.
* For "top" queries, always GROUP BY term (country-level) and compute rank as MIN(rank).

#### 3. Defaults:

* Country-level results only.
* Use region_code only if the user explicitly asks for regions.
* Limit results unless the user asks otherwise.

#### 4. Time series usage:

* Only include week or score when the user asks for trends over time, historical context, or week-over-week score changes.

#### 5. Field guidance:

* Prefer country_code or region_code for filters.
* country_name / region_name are for display only.
* score is normalized; compare trends within a term, not across terms.

Consultas verificadas

As consultas verificadas, antes conhecidas como consultas de ouro, são usadas como referência para o agente melhorar a acurácia da resposta. Elas moldam a estrutura de resposta de um agente e ajudam a ensinar a lógica de negócios usada pela sua organização.

Vamos adicionar dois exemplos para seu agente. Clique em Adicionar consulta e copie / cole a pergunta e a consulta a seguir:

Questão 1:

What are the top search terms in the UK right now?

Consulta 1:

SELECT term, MIN(rank) AS rank
FROM `bigquery-public-data.google_trends.international_top_terms`
WHERE refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)
  AND country_code = 'GB'
GROUP BY term
ORDER BY rank
LIMIT 25;

Antes de salvar essa consulta, vamos executá-la para garantir que ela seja válida.

Tudo certo! Clique em Adicionar para salvar a consulta verificada.

Vamos adicionar mais um exemplo para um caso de uso mais complexo. Clique em Gerenciar consultas e adicione:

Questão 2:

Show the last 12 weeks of interest for the current top 5 terms in Auckland.

Resposta 2:

WITH top5 AS (
  SELECT term, MIN(rank) AS rank
  FROM `bigquery-public-data.google_trends.international_top_terms`
  WHERE refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)
    AND country_code = 'NZ'
    AND region_code = 'NZ-AUK'
  GROUP BY 1
  ORDER BY 2
  LIMIT 5
),
series AS (
  SELECT term, week, score,
    ROW_NUMBER() OVER (PARTITION BY term ORDER BY week DESC) AS rn
  FROM `bigquery-public-data.google_trends.international_top_terms`
  WHERE refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)
    AND country_code = 'NZ'
    AND region_code = 'NZ-AUK'
    AND term IN (SELECT term FROM top5)
)
SELECT week, term, score
FROM series
WHERE rn <= 12
ORDER BY 1 DESC, 3

Antes de passar para a próxima seção, vamos conferir as sugestões geradas pelo Gemini:

Aqui você pode ver algumas consultas verificadas sugeridas. Esse é um ótimo ponto de partida para criar um novo agente no futuro. Não se esqueça de validar qualquer consulta que você adicionar.

Glossário

Vamos adicionar um termo ao glossário. Se sua empresa usa o Dataplex, esses termos são importados diretamente do glossário empresarial no Dataplex Universal Catalog.

Clique em Adicionar termo e copie / cole o exemplo a seguir:

Período:

refresh_date

Definição:

Snapshot date that selects the daily Top 25 term set. All rows for that date belong to the same "what's trending now" snapshot. Attach Historical week and score values after this selection.

Sinônimos:

today, latest, current, now, recent

Em seguida, clique em "Adicionar" e em "Salvar".

Configurações do agente

Na seção Configurações, é possível configurar Marcadores e o Máximo de bytes faturados.

Marcadores

Os rótulos são pares de chave-valor usados para organizar recursos do Google Cloud em grupos lógicos. Para manter o foco deste laboratório, deixe os rótulos em branco.

Máximo de bytes cobrados

Para evitar gerar consultas caras por acidente, vamos definir um limite para o máximo de bytes cobrados por consulta. Se a consulta do agente processar bytes acima desse limite, ela vai falhar sem gerar cobranças. Insira o seguinte valor:

10000000000

10.000.000.000 bytes equivalem a aproximadamente 9,3 GB. Se você não especificar um valor, o máximo de bytes faturados será definido como a cota de uso de consultas por dia do projeto.

5. Como salvar e compartilhar seu agente

Visualizar

Tudo pronto! Vamos testar seu agente antes de continuar. No lado direito da tela, é possível testar o agente de forma dinâmica enquanto faz edições na configuração. A prévia usa automaticamente os novos metadados fornecidos sem salvar ou publicar as mudanças.

Vamos perguntar a quais dados o agente tem acesso. Faça algumas perguntas com suas próprias palavras:

Salvar

Depois de testar alguns comandos, clique em Salvar e em Publicar o agente:

A publicação do agente o disponibiliza no BigQuery Studio, na API Análises de conversação e no Looker Studio Pro (sujeito a licenciamento):

O suporte para outras plataformas e integrações está previsto para versões futuras.

Compartilhar

Você vai receber uma mensagem de confirmação informando que o agente foi publicado. Agora você pode compartilhar esse agente com outros usuários.

Ao compartilhar um agente com outros usuários, você controla o nível de acesso deles atribuindo uma função específica. Essas funções determinam se um colaborador pode apenas visualizar seu agente ou se ele tem o poder de editar e gerenciar a configuração.

É importante observar que essas funções podem ser aplicadas em dois níveis diferentes:

• Nível do projeto: conceder uma função no nível do projeto dá ao usuário essas permissões para todos os agentes nesse projeto do Google Cloud.
• Nível do agente: para um controle mais granular, é possível conceder papéis a um agente específico. Isso é útil quando você quer que um usuário tenha acesso a um agente de dados específico sem ver outros no projeto.

Para um detalhamento de como gerenciar o acesso, consulte a documentação da API Análises de conversação sobre escopos típicos do IAM e as permissões específicas incluídas em cada papel predefinido.

Os papéis predefinidos para o Análises de conversação são os seguintes:

1. Proprietário do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) - Criar, editar, compartilhar e excluir todos os agentes de dados
2. Criador do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator): crie, edite, compartilhe e exclua seus próprios agentes de dados.
3. Editor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor): acesso de chat e edição aos agentes de dados.
4. Usuário do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser): acesso de chat e visualização aos agentes de dados.
5. Leitor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer): acesso somente leitura aos agentes de dados.

6. Criar conversa com um agente

Saia da guia Compartilhar e crie uma conversa:

Ao clicar em Criar conversa, uma nova conversa sem título é gerada.

Vamos perguntar quais termos estão em alta na Inglaterra (você pode substituir por um local da sua escolha):

Based on the top 10 terms in England, how did they trend for the past 3 months?

Descompactando o fluxo de resposta

Normalmente, o agente de dados segue o mesmo fluxo de respostas ao responder a perguntas:

1. Raciocínio: primeiro, o agente "pensa" no comando. Expanda o botão Mostrar raciocínio para conferir insights detalhados sobre o processo de tomada de decisão do agente.
2. Resumo: o agente gera um resumo de alto nível da consulta, do relatório resultante e da visualização.
3. SQL gerado: expanda a seção Esta é a consulta... para inspecionar o SQL. Clique em Abrir no editor para ajustar a consulta manualmente no BigQuery Studio.
4. Resultados de dados: o agente apresenta os resultados da consulta em um formato tabular claro.
5. Visualização: um gráfico aparece ao lado de uma breve descrição. O agente infere automaticamente o melhor tipo de visualização (por exemplo, um gráfico de linhas com várias séries) para seus dados.
6. Insights de dados: o agente resume as principais tendências e conclusões encontradas nos resultados.
7. Perguntas de acompanhamento: por fim, o agente sugere perguntas de acompanhamento relevantes para ajudar você a continuar a análise.

Suporte do BigQuery ML

Vamos acompanhar e perguntar se o agente de dados pode fazer algumas previsões com base nesses resultados. Isso usa funções do BigQuery ML para prever pontos futuros.

Observação: para mais detalhes sobre quais funções de ML são compatíveis, consulte a documentação.

Insira o seguinte comando (substitua "tabuleiro de monopólio" por um termo relevante para sua consulta):

Can you predict and visualize how monopoly board will trend in the next 4 weeks?

É possível ver que o AI_FORECAST foi usado para prever uma série temporal. Não é de se surpreender, mas é interessante notar um grande aumento em agosto de 2021, que coincide com a inauguração da atração Monopoly Lifesized em Londres.

7. Conhecer o catálogo de agentes

Vamos conhecer o catálogo de agentes antes de encerrar. Clique em Catálogo de agentes na parte de cima da janela:

Esta página é sua central para gerenciamento de agentes de dados, organizada nas seguintes seções:

• Meus agentes: os agentes publicados no momento.
• Meus agentes de rascunho: configurações que você salvou, mas ainda não publicou.
• Compartilhados por outras pessoas na sua organização: agentes criados por colegas que você tem permissão para acessar.
• Agentes de amostra do Google: exemplos pré-configurados para ajudar você a começar.

Para qualquer agente gerenciado, é possível editar configurações, duplicar agentes e gerenciar permissões de compartilhamento.

Observação: a análise de conversas no BigQuery é feita com a API Conversational Analytics. As funcionalidades disponíveis no console também podem ser acessadas de forma programática pela API, oferecendo total flexibilidade para renderizar mensagens e integrar com outros agentes e fontes de dados.

8. Conclusão

Parabéns, você criou um agente de dados de análise de conversas. Confira os materiais de referência para saber mais.

Materiais de referência

• Visão geral da análise de conversação no BigQuery
• Visão geral da API Análises de conversação