bigquery-conversational-analytics
Connect, query, and generate data insights for BigQuery datasets and data.
Open source Open in the app JSON README (API)
About
Connect, query, and generate data insights for BigQuery datasets and data.
Details
- Kind
- Plugins
- Topic
- Databases
- Publisher
- gemini-cli-extensions
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.1.8
- Stars
- 28
- Forks
- 2
- Open pull requests
- 1
- Last push
- 2026-08-29T02:30:36Z
- Repository state
- ativo
- License
- Apache-2.0
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
gemini-cli-extensions/bigquery-conversational-analytics
README
# Gemini CLI Extension - BigQuery Conversational 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-conversational-analytics
## **Why Use the BigQuery Conversational Analytics Extension?**
* **Natural Language to insights :** Ask a variety of questions from your BigQuery data and generate intelligent insights.
* **Seamless Workflow:** Stay in your CLI. No need to constantly switch contexts to the GCP console for generating analytics insights. .
* **Leverage prebuilt agent :** Access to advanced insights offered by a built-in agent behind [Conversational Analytics API](https://cloud.google.com/gemini/docs/conversational-analytics-api/overview)
## 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).
* [Node.js](https://nodejs.org/) (the MCP server runs via `npx`).
* A Google Cloud project with the **Data Analytics API with Gemini**, **Gemini for Google Cloud API** and **BigQuery API** enabled.
* Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
* IAM Roles:
* BigQuery User (`roles/bigquery.user`) (for executing queries and view metadata)
* Gemini for Google Cloud (`roles/cloudaicompanion.user`) (to use the conversational analytics API)
## Getting Started
### Installation
To install the extension, use the command:
```bash
gemini extensions install https://github.com/gemini-cli-extensions/bigquery-conversational-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-conversational-analytics [setting name] [--scope <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="<your-gcp-project-id>"
export BIGQUERY_LOCATION="<your-dataset-location>" # Optional
export BIGQUERY_SCOPES="https://www.googleapis.com/auth/bigquery,https://www.googleapis.com/auth/drive" # Optional
export BIGQUERY_MAX_QUERY_RESULT_ROWS=50 # 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:
* Ask for insights
* Using the tables under bigquery-public-data.google\_analytics\_sample , tell me the channels I should focus on and why?
## Supported Tools
This extension provides a comprehensive set of tools:
* `ask_data_insights`: Perform data analysis, get insights, or answer complex questions about the contents of specific BigQuery tables.
* `search_catalog`: Find BigQuery tables relevant to users, natural language 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 Data Analytics](https://github.com/gemini-cli-extensions/bigquery-data-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 npx ENOENT": Node.js/`npx` is not installed or not on your `PATH`. Install Node.js (which provides `npx`).
* "npm error"/network failures on first run: `npx` fetches `@toolbox-sdk/server` on first launch, so it needs network access. Retry once connectivity is available.