Analisar dados com a CLI do Gemini

Nesta página, explicamos como interagir com dados do BigQuery no terminal usando comandos de linguagem natural com a CLI do Gemini. Usar as extensões dedicadas do BigQuery com a CLI do Gemini permite análises de dados e insights baseados em IA diretamente na sua linha de comando. Você pode analisar dados das suas tabelas do BigQuery ou dos conjuntos de dados públicos do BigQuery.

Essas extensões próprias oferecem algumas ferramentas comuns para análise de dados e insights. 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 com programação, depuração, análise de dados e criação de conteúdo. Ele oferece uma experiência orientada por agente para interagir com serviços da Data Cloud, como BigQuery, e outros bancos de dados Google Cloud conhecidos 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 ampliam as capacidades da CLI do Gemini, permitindo que ela se conecte e controle serviços Google Cloud específicos e outras ferramentas. As extensões fornecem contexto e compreensão da API ao Gemini, permitindo a interação por conversa. É 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 se integra usando a MCP Toolbox.

Sobre as extensões do BigQuery

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

Extensão de análise de dados do BigQuery
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. Você também pode gerar previsões ou fazer uma análise de contribuição usando ferramentas avançadas integradas. As ferramentas dessa 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.
Extensão das Análises de conversação do BigQuery
Use essa 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 dessa extensão ajudam a CLI do Gemini a enviar sua pergunta em linguagem natural para um agente integrado e hospedado e responder com insights mais detalhados dos seus dados.

Ferramentas de análise de dados do BigQuery

A extensão de análise de dados do BigQuery oferece as seguintes ferramentas:

Categoria Ferramenta Exemplo de comando de linguagem natural
Informações de conjunto de dados e 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, mostre os 10 pacotes pypi mais baixados neste mês
Previsão de série temporal forecast Usando bigquery-public-data.pypi.file_downloads, preveja os downloads dos últimos quatro meses de 2025 para o pacote urllib3
Análise de contribuição analyze_contribution Analise a contribuição do país para a receita na tabela bigquery-public-data.google_analytics_sample.ga_sessions_20170801

Ferramentas de análise de conversação

A extensão Conversational Analytics oferece as seguintes ferramentas:

Categoria Ferramenta Exemplo de comando de 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, diga em quais canais 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 projeto do Google Cloud .

  • Para a extensão de análise de dados, ative as seguintes APIs:

    • BigQuery
    • Para usar a ferramenta search_catalog: Dataplex Universal Catalog

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

    • BigQuery
    • Dataplex Universal 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 Gemini, peça ao administrador para conceder a você os seguintes papéis do IAM em 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 papéis personalizados ou outros papéis predefinidos.

Instalar as extensões do BigQuery

Instale as extensões do BigQuery e use-as para analisar e explorar 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 ID do projeto do Google Cloud.

    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 é para usar o OAuth do lado do cliente. Por exemplo: export BIGQUERY_USE_CLIENT_OAUTH=true

  3. Instale a extensão de análise de dados do BigQuery ou de análise conversacional usando o comando gemini extension install:

    • Opcional: instale a extensão de análise de dados do BigQuery:

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

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

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

  4. Inicie a CLI do Gemini no modo interativo para analisar e explorar 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 analisar seus dados

Insira comandos na CLI do Gemini. Use os exemplos a seguir para começar.

Analisar e explorar tabelas

Com os exemplos de comandos a seguir, você pode explorar e analisar suas tabelas.

  • Comando de exemplo para encontrar tabelas relacionadas a downloads do PyPi:

    Find tables related to PyPi downloads

    Exemplo de resposta

    A CLI 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 pacotes do PyPI mais 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

Gerar insights mais detalhados usando a ferramenta ask_data_insights

A ferramenta ask_data_insights aciona um agente na API Conversational Analytics do BigQuery 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 você deve 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 sob demanda do BigQuery ou os preços por 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 ela são cobradas de acordo com os preços padrão do BigQuery.

A seguir