> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/integracao/google-bigquery.md). # Google BigQuery O módulo **Google BigQuery** permite consultar ou inserir dados no Google BigQuery (o serviço de armazenamento e análise de dados do Google) sem sair do fluxo. É útil para buscar informações de um grande volume de dados já existente na sua empresa (ex.: histórico de compras, cadastro de clientes) e usar essas informações para personalizar o atendimento, ou para registrar dados do fluxo direto em uma tabela do BigQuery.

Imagem 1 - Visão geral do módulo Google BigQuery na área de trabalho do fluxo no Hyperflow Integrações.

*** ### 🧭 Como acessar 1. No menu lateral, clique em **Gerenciamento de aplicativos**. 2. Em seguida, clique em **Fluxos**. 3. Abra ou crie um fluxo e acesse a área de trabalho do fluxo. 4. No painel de módulos, localize a categoria **Integração** (identificada pela cor azul). 5. Arraste o módulo **Google BigQuery** para a área de trabalho do fluxo.

Imagem 2 - Painel de módulos com a categoria Integração expandida e o módulo Google BigQuery visível.

*** ### 🔍 Conhecendo o módulo Ao clicar duas vezes no módulo na área de trabalho do fluxo, um painel de configuração é aberto na lateral da tela. {% hint style="warning" %} **Antes de usar este módulo:** é preciso ter uma integração do tipo **Google BigQuery** já cadastrada em **Integrações**, com as credenciais de acesso ao seu projeto do Google Cloud. Se ainda não tiver uma, cadastre primeiro em Integrações e depois volte a este módulo para selecioná-la. {% endhint %}

Imagem 3 - Painel de configuração do módulo Google BigQuery aberto.

*** #### 🔌 Integração No campo **Integração**, selecione qual credencial do Google BigQuery, entre as já cadastradas em **Integrações**, será usada por este módulo. Se nenhuma integração aparecer na lista, clique no link exibido para ser direcionado à tela de cadastro. *** #### 🧩 Tipo de operação No campo **Tipo**, escolha o que este módulo vai fazer: * **Consulta** — busca dados no BigQuery. * **Inserção** — envia novos dados para uma tabela do BigQuery. Os campos exibidos a seguir mudam de acordo com essa escolha.

Imagem 4 - Campo Tipo com as opções Consulta e Inserção.

*** #### 🔎 Consulta (quando o tipo é "Consulta") No campo **Consulta**, escreva o comando SQL que será executado no BigQuery. Você pode usar variáveis do fluxo dentro do comando. {% hint style="info" %} Inclua o nome do projeto e do conjunto de dados diretamente no comando (formato `projeto.conjunto_de_dados.tabela`), já que o módulo não tem campos separados para isso no modo Consulta. {% endhint %} Exemplo: ```sql SELECT * FROM meu-projeto.meus_dados.clientes WHERE telefone = '{{input.phone}}' ```

Imagem 5 - Campo Consulta preenchido com um comando SQL de exemplo.

*** #### ➕ Inserção (quando o tipo é "Inserção") Quando o tipo escolhido é **Inserção**, os campos abaixo são exibidos: | Campo | O que preencher | | ----------------------- | ----------------------------------------------------------------------------------------------- | | ID do conjunto de dados | Nome do conjunto de dados no BigQuery onde os dados serão inseridos. Aceita variáveis do fluxo. | | ID da tabela | Nome da tabela dentro do conjunto de dados. Aceita variáveis do fluxo. | | Dados | Os dados a inserir, no formato JSON (uma lista de objetos). | Exemplo do campo Dados: ```json [ { "nome": "{{user.name}}", "telefone": "{{input.phone}}" } ] ```

Imagem 6 - Campos de Inserção preenchidos com ID do conjunto de dados, ID da tabela e Dados em JSON.

*** #### 🔀 Saídas do módulo O módulo tem duas saídas: * **Sucesso** — segue com o resultado da consulta (uma lista de registros) disponível para os próximos módulos do fluxo. * **Erro** — segue quando não é possível executar a consulta ou inserção (ex.: comando SQL inválido, tabela inexistente).

Imagem 7 - Módulo na área de trabalho do fluxo mostrando as duas saídas disponíveis.

*** ### 💡 Caso de uso **Cenário:** uma empresa quer que o chatbot busque o histórico de compras de um cliente, armazenado no BigQuery, para personalizar o atendimento. **Configuração:** 1. Adicione o módulo **Google BigQuery** ao fluxo. 2. No campo **Integração**, selecione a credencial já cadastrada do BigQuery da empresa. 3. No campo **Tipo**, escolha **Consulta**. 4. No campo **Consulta**, escreva: `SELECT ultima_compra, valor_total FROM minha-empresa.vendas.clientes WHERE telefone = '{{input.phone}}'`. 5. Conecte a saída de **Sucesso** a um módulo que envie uma mensagem usando os dados retornados, e a saída de **Erro** a uma mensagem padrão de indisponibilidade. **Resultado:** o fluxo consulta automaticamente o histórico de compras do cliente pelo telefone informado e usa essa informação na conversa. *** ### 📌 Dicas úteis * No modo **Consulta**, sempre inclua o nome completo da tabela (`projeto.conjunto_de_dados.tabela`) dentro do comando SQL. * No modo **Inserção**, o campo **Dados** espera uma lista de objetos em JSON, mesmo que você vá inserir um único registro (ex.: `[{ "campo": "valor" }]`). * Use variáveis do fluxo tanto na consulta SQL quanto nos dados de inserção para personalizar cada execução. * Certifique-se de que a integração selecionada tem permissão de acesso ao conjunto de dados e à tabela usados no comando. *** ### 📝 Resumo * O módulo **Google BigQuery** consulta ou insere dados no Google BigQuery diretamente do fluxo. * É necessário ter uma integração do tipo Google BigQuery já cadastrada em **Integrações** antes de usar este módulo. * O campo **Tipo** define se a operação é uma **Consulta** (SQL) ou uma **Inserção** (dados em JSON). * O módulo tem uma saída de **Sucesso**, com o resultado disponível para o fluxo, e uma saída de **Erro**.