BigQuery Data Analytics with Gemini CLI — Part 1 | by Rachael Deacon-smith | Google Cloud – Community | Oct, 2025

A Deep Dive and Tutorial into the new BigQuery Extension for Gemini CLI

Gemini CLI recently upped its game for data practitioners with the launch of the BigQuery Data Analytics extension! This extension comes with a suite of tools that let you securely and reliably ask natural language questions about your BigQuery data. You can generate insights — from data discovery and advanced analytics to forecasts and contribution analysis — all directly from your terminal.

This post introduces the new BigQuery Data Analytics extension and guides you through how to use it. Let’s dive in…

A quick recap: What is Gemini CLI?

It’s basically Gemini integrated in your terminal. Instead of typing shell commands, you interact with your terminal using natural language. And because Gemini CLI is an agent, not a chatbot, it can actually interact with your development environment and do things — for example, it can generate code, create apps and update your Git repository.

For data practitioners, Gemini CLI provides direct terminal access to their data, enabling end-to-end data workflows — from ingestion and transformation to analysis and forecasting — without context switching between IDEs, notebooks and the BigQuery UI.

Why do we need a BigQuery extension for Gemini CLI?

Gemini CLI is pretty capable as is. You can ask natural language questions about data stored in BigQuery, like: “what tables are in BigQuery’s public dataset thelook_ecommerce?” and Gemini can translate this into the following bq shell command:

bq query --project_id=bigquery-public-data --use_legacy_sql=false 
'SELECT table_name FROM thelook_ecommerce.INFORMATION_SCHEMA.TABLES' 

This is fine for simple tasks, but this approach relies on Gemini’s general knowledge to generate and chain together the correct shell commands and SQL queries. You’re not guaranteed consistency on execution, and this also becomes less reliable for complex analytics such as time series forecasting or contribution analysis, where we’d want to be sure Gemini is using the appropriate BigQuery functions.

The BigQuery extension solves this by providing a suite of tools dedicated to solving both the common and complex BigQuery tasks. The extension comes equipped with a ready-to-go locally hosted MCP server, eliminating the need for you to have to set up your own server.

A deeper look at the BigQuery Data Analytics extension

You can install the extension with a simple command (check out the tutorial below for a step by step guide):

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

Press enter or click to view image in full size

Once installed, you will have a new .gemini/extensions/bigquery-data-analytics directory populated with three core components:

1. A locally hosted MCP server that can be used by Gemini CLI. The server leverages the toolbox binary which holds all of the logic for the actual tool execution as well as the settings defined in gemini-extension.json:

{
"name": "bigquery-data-analytics",
"version": "0.1.1",
"description": "Connect, query, and generate data insights for BigQuery datasets and data.",
"mcpServers": {
"bigquery_data_analytics": {
"command": "${extensionPath}${/}toolbox",
"args": [
"--tools-file",
"${extensionPath}${/}tools.yaml",
"--stdio"
]
}
},
"contextFileName": "BIGQUERY.md"
}

2. A declarative suite of BigQuery tools that can be executed on the MCP server:

• execute_sql: Executes a SQL query.
• forecast: Forecast time series data.
• analyze_contribution: Perform contribution analysis, also called key driver analysis.
• search_catalog: Search for tables based on the provided query
• get_dataset_info: Get dataset metadata.
• get_table_info: Get table metadata.
• list_dataset_ids: Lists dataset ids in the database.
• list_table_ids: Lists table ids in the database.

These tools are defined in the tools.yaml file and are owned and maintained by Google:

sources:
bigquery-source:
kind: "bigquery"
project: ${BIGQUERY_PROJECT}
location: ${BIGQUERY_LOCATION:}
useClientOAuth: ${BIGQUERY_USE_CLIENT_OAUTH:false}
tools:
analyze_contribution:
kind: bigquery-analyze-contribution
source: bigquery-source
description: Use this tool to analyze the contribution about changes to key metrics in multi-dimensional data.
execute_sql:
kind: bigquery-execute-sql
source: bigquery-source
description: Use this tool to execute sql statement.
forecast:
kind: bigquery-forecast
source: bigquery-source
description: Use this tool to forecast time series data.
...

3. A BigQuery.md context file that contains extension-specific system instructions. These instructions are appended to the Gemini CLI core instructions and guide the agent on critical scenarios like handling missing environment variables, or permission errors during tool usage:

...
**Handle Missing Variables**: 
If a command fails with an error message containing a placeholder like 
`${BIGQUERY_PROJECT}`, it signifies a missing environment variable. 
Inform the user which variable is missing and instruct them to set it.
...

Gemini CLI Super Power

Equipped with these tools, Gemini can now reason about your natural language question and determine the most appropriate tool to call. If a tool call fails, for example, the SQL query is incorrect, the agent is usually savvy enough to autonomously debug the issue and try again.

One of Gemini CLI’s biggest advantages is that it can integrate your BigQuery interactions with its other capabilities. For example, let’s say you have ecommerce data stored in BigQuery. You can ask Gemini CLI to:

1. Forecast what the historical return rate of products will be next month.
2. Search the web for any information on upcoming trends that may influence buyer behaviour for products.
3. Generate a report that generates charts and summarizes all of the above.
4. Modify your local Git repo by adding and committing the generated report file.