Analyze data with the Gemini CLI

Note: The BigQuery CLI extensions are based on MCP Toolbox for Databases. MCP Toolbox for Databases is in beta (pre-v1.0) and may see breaking changes until the first stable release (v1.0).

This page explains how to interact with BigQuery data in your terminalby using natural-language prompts with theGemini CLI. Using thededicated BigQueryextensions with the Gemini CLIenables AI-driven data analysis and insights directly within your command line.You can analyze data from your BigQuery tables, or from tables inthe BigQuery public datasets.

These first-party extensions provide some common tools for data analysis andinsights. To build your own tools, seeUse BigQuery with MCP, Gemini CLI, and other agents.

About Gemini CLI and extensions

The Gemini CLI is an open-source conversational AI agent fromGoogle that accelerates development workflows and assists with coding,debugging, data exploration, and content creation. It offers an agent-drivenexperience to interact with Data Cloud services, such asBigQuery, and other popular Google Cloud databases andopen-source databases.

For more information about the Gemini CLI, see theGemini CLI documentation.

How extensions work

Extensions expand the capabilities of the Gemini CLI, letting itconnect to and control specific Google Cloud services and other tools. Theextensions provide Gemini with context and API understanding,enabling conversational interaction. You can load the extensions from GitHubURLs, local directories, or registries. These extensions offer tools, slashcommands, and prompts. These are separate from IDE extensions, such asGemini Code Assist, which integrate using the MCP Toolbox.

About the BigQuery extensions

BigQuery offers the following extensions to work withBigQuery data through the Gemini CLI:

BigQuery Data Analytics extension

Use this extension todiscover data, learn more about BigQuery tables and datasets,and ask natural language questions about your datasets. You can alsogenerate forecasts or run a contribution analysis using built-in advancedtools. The tools in this extension help the Gemini CLI writeSQL queries based on your natural language questions, and then execute thequeries to provide answers for your questions.

BigQuery Conversational Analytics extension

Use this extensionto get advanced insights from your BigQuery data using apre-hosted, server-side analytics agent. The tools in this extension helpthe Gemini CLI send your natural language question to abuilt-in, hosted agent and respond with deeper insights from your data.

BigQuery Data Analytics tools

TheBigQuery Data Analytics extension provides the followingtools:

Category	Tool	Example natural language prompt
Dataset and table information	get_dataset_info	Get information about the dataset bigquery-public-data.pypi
	get_table_info	Get information about the table bigquery-public-data.pypi.file_downloads
	list_dataset_ids	List all ML datasets in the project bigquery-public-data
	list_table_ids	List all tables in the dataset bigquery-public-data.pypi
Search	search_catalog	Find tables related to PyPi downloads
SQL execution	execute_sql	Using bigquery-public-data.pypi.file_downloads, show me the top 10 downloaded pypi packages this month
Time-series forecasting	forecast	Using bigquery-public-data.pypi.file_downloads, forecast the downloads for the last four months of 2025 for package urllib3
Contribution analysis	analyze_contribution	Analyze the contribution of country to revenue in the bigquery-public-data.google_analytics_sample.ga_sessions_20170801 table

Conversational Analytics tools

TheConversational Analytics extensionprovides the following tools:

Category	Tool	Example natural language prompt
Search	search_catalog	Find tables related to PyPi downloads
Conversational analytics	ask_data_insights	Using the tool ask_data_insights and the tables under bigquery-public-data.google_analytics_sample, tell me the channels I should focus on and why

Before you begin

Before you begin, you need the following:

• Access to at least one Google Cloud project.

• For the Data Analytics extension, enable the following APIs:

  • BigQuery
  • To use thesearch_catalog tool: Dataplex Universal Catalog

• For the Conversational Analytics extension, enable the following APIs:

  • BigQuery
  • Dataplex Universal Catalog
  • To use theask_data_insights tool: Gemini for Google Cloud API,Gemini, and Data Analytics API with Gemini

Required roles

To get the permissions that you need to use the BigQuery extensions with Gemini CLI, ask your administrator to grant you the following IAM roles on Resource Manager resources (projects, folders, and organizations) or lower-level resources like datasets:

• Run BigQuery queries in a Google Cloud project:BigQuery User (roles/bigquery.user)
• Use the foundational metadata tools to get BigQuery dataset and table metadata:BigQuery Metadata Viewer (roles/bigquery.metadataViewer)
• Use the Conversational Analytics extension:Gemini for Google Cloud User (roles/cloudaicompanion.user)

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Install the BigQuery extensions

Install the BigQuery extensions and then use them to explore andanalyze your data.

1. Install the Gemini CLI.

2. Set the environment variables to connect to your BigQueryproject:

   exportBIGQUERY_PROJECT="PROJECT_ID"

   ReplacePROJECT_ID with your Google Cloudproject ID.

   You can also set these optional environment variables:

   • BIGQUERY_LOCATION: the dataset location—for example:exportBIGQUERY_LOCATION="us"
   • BIGQUERY_USE_CLIENT_OAUTH: whether to use client-side OAuth—forexample:export BIGQUERY_USE_CLIENT_OAUTH=true

3. Install the BigQuery Data Analytics or ConversationalAnalytics extension using thegemini extension install command:

   • Optional: install the BigQuery Data Analytics extension:

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

   • Optional: install the BigQuery Conversational Analyticsextension:

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

4. Start the Gemini CLI in interactive mode to explore andanalyze your data:

   gemini

   The CLI automatically loads the BigQuery extension and itstools, which you can use to interact with your data.

Note: if you install both of the BigQuery extensions, the Gemini CLI might use tools from either extension to answer your questions. This could have a billing impact, as there is additional billing impact when using Conversational Analytics tools. For more information, seePricing.

Example prompts to explore and analyze your data

Enter prompts in the Gemini CLI. You can use the followingexamples to get started.

Explore and analyze tables

The following example prompts let you explore and analyze your tables.

• Example prompt to find tables related to PyPi downloads:

  Find tables related to PyPi downloads

  Example response

  The Gemini CLI returns a list of related tables:

  ✦ 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

• Example prompt to show the top ten downloaded PyPI packages this month:

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

  Example response

  The Gemini CLI returns the top 10 packages:

  ✦ 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

Run deeper insights using theask_data_insights tool

Theask_data_insights tool triggers an agent on the BigQueryConversational Analytics API to answer your questions. The server-side agentgathers additional context about your data and offers more insights.

• Example prompt to get insights on channels to focus on:

  Using ask_data_insights and using the tables underbigquery-public-data.google_analytics_sample, tell me the channels I shouldfocus on and why

  Example response

  The Gemini CLI returns recommendations based on the analysis:

  Based on the analysis of the Google Analytics sample data, here are thechannels 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.

Pricing

There is no additional cost for using metadata tools (such asget_dataset_info,get_table_info,list_dataset_ids, andlist_table_ids)or thesearch_catalog tool.

Tools that run queries, includingexecute_sql,forecast, andanalyze_contribution, are billed according toBigQuery on-demand pricingorBigQuery capacity pricing,depending on your project configuration.

During beta (pre-v1.0), theask_data_insights tool is offered at no additionalcost; however, any BigQuery queries that this tool triggers arebilled according to standard BigQuery pricing.

What's next

• Learn more aboutusing BigQuery with MCP, Gemini CLI, and other agents.
• Learn more aboutGemini in BigQuery.
• See theData Analytics extension on GitHub.
• See theConversational Analytics extension on GitHub.