https://github.com/gemini-cli-extensions/bigquery-data-analytics
https://github.com/gemini-cli-extensions/bigquery-data-analytics
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/gemini-cli-extensions/bigquery-data-analytics
- Owner: gemini-cli-extensions
- License: apache-2.0
- Created: 2025-09-12T15:34:46.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-01-29T00:18:02.000Z (5 months ago)
- Last Synced: 2026-01-29T13:24:46.311Z (5 months ago)
- Size: 172 KB
- Stars: 28
- Watchers: 0
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-gemini-cli-extensions - BigQuery Data Analytics - Developers can effortlessly connect, interact, and generate data insights with BigQuery datasets and data using natural language commands. (Data & Analytics / Observability & Monitoring)
README
# Gemini CLI Extension - BigQuery Data Analytics
> [!NOTE]
> This extension is currently in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0).
Developers can effortlessly connect, interact, and generate data insights with [BigQuery](https://cloud.google.com/bigquery/docs) datasets and data using natural language commands.
Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md).
> [!IMPORTANT]
> **We Want Your Feedback!**
> Please share your thoughts with us by filling out our feedback [form][form].
> Your input is invaluable and helps us improve the project for everyone.
[form]: https://docs.google.com/forms/d/e/1FAIpQLSfEGmLR46iipyNTgwTmIDJqzkAwDPXxbocpXpUbHXydiN1RTw/viewform?usp=pp_url&entry.157487=bigquery-data-analytics
## Why Use the BigQuery Data Analytics Extension?
* **Natural Language to data analytics :** Find required BigQuery tables and ask analytical questions in natural language.
* **Seamless Workflow:** Stay in your CLI. No need to constantly switch contexts to the GCP console for generating analytical insights.
* **Run advanced analytics :** Generate forecasts, run a contributions analysis using built-in advanced tools.
## Prerequisites
Before you begin, ensure you have the following:
* [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed with version **+v0.6.0**.
* Setup Gemini CLI [Authentication](https://github.com/google-gemini/gemini-cli/tree/main?tab=readme-ov-file#-authentication-options).
* A Google Cloud project with the **BigQuery API** enabled.
* Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
* IAM Permissions:
* BigQuery User (`roles/bigquery.user`)
## Getting Started
### Installation
To install the extension, use the command:
```bash
gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics
```
### Configuration
You will be prompted to configure the following settings during installation. These settings are saved in an `.env` file within the extension's directory.
* `BIGQUERY_PROJECT`: The GCP project ID.
* `BIGQUERY_LOCATION`: (Optional) The dataset location.
To view or update your configuration:
**List Settings:**
* Terminal: `gemini extensions list`
* Gemini CLI: `/extensions list`
**Update Settings:**
* Terminal: `gemini extensions config bigquery-data-analytics [setting name] [--scope ]`
* `setting name`: (Optional) The single setting to configure.
* `scope`: (Optional) The scope of the setting in (`user` or `workspace`). Defaults to `user`.
* Currently, you must restart the Gemini CLI for changes to take effect. We recommend using `gemini --resume` to resume your session.
Alternatively, you can manually set these environment variables before starting the Gemini CLI:
```bash
export BIGQUERY_PROJECT=""
export BIGQUERY_LOCATION="" # Optional
```
> [!NOTE]
> * Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
> * See [Troubleshooting](#troubleshooting) for debugging your configuration.
### Start Gemini CLI
To start the Gemini CLI, use the following command:
```bash
gemini
```
## Usage Examples
Interact with BigQuery using natural language right from your IDE:
* **Find Data:**
* "Find tables related to PyPi downloads"
* "Find tables related to Google analytics data in the dataset bigquery-public-data"
* **Generate Analytics and insights:**
* "Using bigquery-public-data.pypi.file\_downloads show me the top 10 downloaded pypi packages this month."
* “Using bigquery-public-data.pypi.file\_downloads can you forecast downloads for the last four months of 2025 for package urllib3?”
## Supported Tools
This extension provides a comprehensive set of tools:
* `execute_sql`: Executes a SQL query.
* `forecast`: Forecast time series data.
* `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.
* `analyze_contribution`: Perform contribution analysis, also called key driver analysis.
* `search_catalog`: Search for tables based on the provided query.
## Additional Extensions
Find additional extensions to support your entire software development lifecycle at [github.com/gemini-cli-extensions](https://github.com/gemini-cli-extensions), including:
* [BigQuery Conversational Analytics](https://github.com/gemini-cli-extensions/bigquery-conversational-analytics)
* and more!
## Troubleshooting
Use `gemini --debug` to enable debugging.
Common issues:
* "failed to find default credentials: google: could not find default credentials.": Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) for more information.
* "✖ Error during discovery for server: MCP error -32000: Connection closed": The database connection has not been established. Ensure your configuration is set via environment variables.
* "✖ MCP ERROR: Error: spawn /Users/USER/.gemini/extensions/bigquery-data-analytics/toolbox ENOENT": The Toolbox binary did not download correctly. Ensure you are using Gemini CLI v0.6.0+.
* "cannot execute binary file": The Toolbox binary did not download correctly. Ensure the correct binary for your OS/Architecture has been downloaded. See [Installing the server](https://googleapis.github.io/genai-toolbox/getting-started/introduction/#installing-the-server) for more information.