Analisar dados com a CLI do Gemini

Nesta página, explicamos como interagir com dados do BigQuery no terminal usando comandos em linguagem natural com a CLI do Gemini. O uso das extensões dedicadas do BigQuery com a CLI do Gemini permite insights e análises de dados orientados por IA diretamente na linha de comando. É possível analisar dados das tabelas do BigQuery ou de tabelas nos conjuntos de dados públicos do BigQuery.

Essas extensões próprias fornecem algumas ferramentas comuns para insights e análise de dados. Para criar suas próprias ferramentas, consulte Usar o BigQuery com a MCP, a CLI do Gemini e outros agentes.

Sobre a CLI do Gemini e as extensões

A CLI do Gemini é um agente de IA conversacional de código aberto do Google que acelera os fluxos de trabalho de desenvolvimento e ajuda na codificação, depuração, exploração de dados e criação de conteúdo. Ela oferece uma experiência orientada por agente para interagir com serviços do Data Cloud, como o BigQuery, e outros bancos de dados Google Cloud populares e de código aberto.

Para mais informações sobre a CLI do Gemini, consulte a documentação da CLI do Gemini.

Como as extensões funcionam

As extensões expandem os recursos da CLI do Gemini, permitindo que ela se conecte e controle serviços específicos Google Cloud e outras ferramentas. As extensões fornecem contexto e compreensão da API ao Gemini, permitindo a interação conversacional. É possível carregar as extensões de URLs do GitHub, diretórios locais ou registros. Essas extensões oferecem ferramentas, comandos de barra e comandos. Elas são separadas das extensões de IDE, como o Gemini Code Assist, que são integradas usando a MCP Toolbox.

Sobre as extensões do BigQuery

O BigQuery oferece as seguintes extensões para trabalhar com dados do BigQuery pela CLI do Gemini:

Extensão do BigQuery Data Analytics
Use essa extensão para descobrir dados, saber mais sobre tabelas e conjuntos de dados do BigQuery e fazer perguntas em linguagem natural sobre seus conjuntos de dados. Também é possível gerar previsões ou executar uma análise de contribuição usando ferramentas avançadas integradas. As ferramentas nessa extensão ajudam a CLI do Gemini a escrever consultas SQL com base nas suas perguntas em linguagem natural e, em seguida, executar as consultas para fornecer respostas às suas perguntas.
Extensão do BigQuery Análises de conversação
Use esta extensão para receber insights avançados dos seus dados do BigQuery usando um agente de análise pré-hospedado do lado do servidor. As ferramentas nessa extensão ajudam a CLI do Gemini a enviar sua pergunta em linguagem natural para um agente hospedado integrado e responder com insights mais detalhados dos seus dados.

Ferramentas do BigQuery Data Analytics

A extensão do BigQuery Data Analytics fornece as seguintes ferramentas:

Categoria Ferramenta Exemplo de comando em linguagem natural
Informações do conjunto de dados e da tabela get_dataset_info Receber informações sobre o conjunto de dados bigquery-public-data.pypi
get_table_info Receber informações sobre a tabela bigquery-public-data.pypi.file_downloads
list_dataset_ids Listar todos os conjuntos de dados de ML no projeto bigquery-public-data
list_table_ids Listar todas as tabelas no conjunto de dados bigquery-public-data.pypi
Pesquisar search_catalog Encontrar tabelas relacionadas a downloads do PyPi
Execução de SQL execute_sql Usando bigquery-public-data.pypi.file_downloads, mostrar os 10 principais pacotes do pypi baixados neste mês
Previsão de série temporal forecast Usando bigquery-public-data.pypi.file_downloads, prever os downloads dos últimos quatro meses de 2025 para o pacote urllib3
Análise de contribuição analyze_contribution Analisar a contribuição do país para a receita na tabela bigquery-public-data.google_analytics_sample.ga_sessions_20170801

Ferramentas do Análises de conversação

A extensão Análises de conversação fornece as seguintes ferramentas:

Categoria Ferramenta Exemplo de comando em linguagem natural
Pesquisar search_catalog Encontrar tabelas relacionadas a downloads do PyPi
Análises de conversação ask_data_insights Usando a ferramenta ask_data_insights e as tabelas em bigquery-public-data.google_analytics_sample, informar os canais em que devo me concentrar e por quê

Antes de começar

Antes de começar, os seguintes itens são necessários:

  • Acesso a pelo menos um Google Cloud projeto.

  • Para a extensão do Data Analytics, ative as seguintes APIs:

    • BigQuery
    • Para usar a ferramenta search_catalog: Knowledge Catalog

  • Para a extensão do Análises de conversação, ative as seguintes APIs:

    • BigQuery
    • Knowledge Catalog
    • Para usar a ferramenta ask_data_insights: API Gemini para Google Cloud, Gemini e API Data Analytics com Gemini

Funções exigidas

Para receber as permissões necessárias para usar as extensões do BigQuery com a CLI do Gemini, peça ao administrador para conceder a você as seguintes funções do IAM nos recursos do Resource Manager (projetos, pastas e organizações) ou recursos de nível inferior, como conjuntos de dados:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando personalizados papéis ou outros predefinidos papéis.

Instalar as extensões do BigQuery

Instale as extensões do BigQuery e use-as para explorar e analisar seus dados.

  1. Instale a CLI do Gemini.

  2. Defina as variáveis de ambiente para se conectar ao projeto do BigQuery:

    export BIGQUERY_PROJECT="PROJECT_ID"

    Substitua PROJECT_ID pelo seu Google Cloud ID do projeto.

    Também é possível definir estas variáveis de ambiente opcionais:

    • BIGQUERY_LOCATION: o local do conjunto de dados. Por exemplo: export BIGQUERY_LOCATION="us"
    • BIGQUERY_USE_CLIENT_OAUTH: se deve usar o OAuth do lado do cliente. Por exemplo: export BIGQUERY_USE_CLIENT_OAUTH=true

  3. Instale a extensão do BigQuery Data Analytics ou do Conversational Analytics usando o comando gemini extension install:

    • Opcional: instalar a extensão do BigQuery Data Analytics:

      gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics

    • Opcional: instalar a extensão do BigQuery Análises de conversação:

      gemini extensions install https://github.com/gemini-cli-extensions/bigquery-conversational-analytics

  4. Inicie a CLI do Gemini no modo interativo para explorar e analisar seus dados:

    gemini

    A CLI carrega automaticamente a extensão do BigQuery e as ferramentas dela, que podem ser usadas para interagir com seus dados.

Exemplos de comandos para explorar e analisar seus dados

Insira comandos na CLI do Gemini. Você pode usar os exemplos a seguir para começar.

Explorar e analisar tabelas

Os exemplos de comandos a seguir permitem explorar e analisar suas tabelas.

  • Exemplo de comando para encontrar tabelas relacionadas a downloads do PyPi:

    Find tables related to PyPi downloads

    Exemplo de resposta

    A CLI do Gemini retorna uma lista de tabelas relacionadas:

    ✦ I found the following tables related to PyPi downloads:

    *   file_downloads: projects/bigquery-public-data/datasets/pypi/tables/file_downloads
    *   distribution_metadata: projects/bigquery-public-data/datasets/pypi/tables/distribution_metadata

  • Exemplo de comando para mostrar os dez principais pacotes do PyPI baixados neste mês:

    Using bigquery-public-data.pypi.file_downloads, show me the top 10
downloaded pypi packages this month

    Exemplo de resposta

    A CLI do Gemini retorna os 10 principais pacotes:

    ✦ Here are the top 10 most downloaded PyPI packages this month:

    1.  boto3: 685,007,866 downloads
    2.  botocore: 531,034,851 downloads
    3.  urllib3: 512,611,825 downloads
    4.  requests: 464,595,806 downloads
    5.  typing-extensions: 459,505,780 downloads
    6.  certifi: 451,929,759 downloads
    7.  charset-normalizer: 428,716,731 downloads
    8.  idna: 409,262,986 downloads
    9.  grpcio-status: 402,535,938 downloads
    10. aiobotocore: 399,650,559 downloads

Executar insights mais detalhados usando a ferramenta ask_data_insights

A ferramenta ask_data_insights aciona um agente na API BigQuery Análises de conversação para responder às suas perguntas. O agente do lado do servidor coleta mais contexto sobre seus dados e oferece mais insights.

  • Exemplo de comando para receber insights sobre os canais em que se concentrar:

    Using ask_data_insights and using the tables under
bigquery-public-data.google_analytics_sample, tell me the channels I should
focus on and why

    Exemplo de resposta

    A CLI do Gemini retorna recomendações com base na análise:

    Based on the analysis of the Google Analytics sample data, here are the
channels you should focus on and why:

|     Channel      | Total Visits | Total Pageviews | Total Transactions | Total Revenue |
| ---------------- | ------------ | --------------- | ------------------ | ------------- |
| Referral         |      104,838 |         707,597 |              5,543 |   $651,429.91 |
| Direct           |      143,026 |         584,840 |              2,219 |   $434,840.55 |
| Organic Search   |      381,561 |       1,569,218 |              3,581 |   $326,380.51 |
| Display          |        6,262 |          34,202 |                152 |    $78,337.46 |
| Paid Search      |       25,326 |         136,060 |                479 |    $43,558.90 |
| Social           |      226,117 |         398,690 |                131 |     $4,916.54 |
| Affiliates       |       16,403 |          47,417 |                  9 |       $597.38 |
| (Other)          |          120 |             442 |                  1 |         $9.99 |

  Recommendations:

    1.  Prioritize referral traffic:
        *   Why: This is a highly valuable channel. It brings in the most
            revenue and has a high number of transactions, despite not
            having the highest number of visits. This indicates that
            traffic from referrals is highly qualified and converts
            well.
        *   Action: Identify your top referring websites and build
            stronger relationships with them. Look for similar websites
            to partner with.

    2.  Nurture your direct traffic:
        *   Why: Direct traffic is your second-highest revenue source.
            These are likely returning customers or people who know your
            brand well.

Preços

Não há custo adicional para usar ferramentas de metadados (como get_dataset_info, get_table_info, list_dataset_ids e list_table_ids) ou a ferramenta search_catalog.

As ferramentas que executam consultas, incluindo execute_sql, forecast, e analyze_contribution, são faturadas de acordo com os preços on demand do BigQuery ou os preços de capacidade do BigQuery, dependendo da configuração do projeto.

Durante a versão Beta (pré-v1.0), a ferramenta ask_data_insights é oferecida sem custo adicional. No entanto, todas as consultas do BigQuery acionadas por essa ferramenta são faturadas de acordo com os preços padrão do BigQuery.

A seguir