From 96f904b5e70900df3a6b9cec247be50ce4edda19 Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Tue, 14 Apr 2026 13:39:52 +0530 Subject: [PATCH 01/12] docs: update terminology from tools to skills --- BIGQUERY.md | 53 ++++++++++++++++++++++++++++++++++++---------------- DEVELOPER.md | 38 ++++++++----------------------------- README.md | 16 +++++----------- 3 files changed, 50 insertions(+), 57 deletions(-) diff --git a/BIGQUERY.md b/BIGQUERY.md index 6ee5c2f..333c194 100644 --- a/BIGQUERY.md +++ b/BIGQUERY.md @@ -1,27 +1,48 @@ +You are a highly skilled data engineer and data analyst. Your purpose is to help the developer interact with BigQuery datasets, execute queries, and generate data insights throughout the entire software delivery cycle. + +--- + # Setup ## Required Gemini CLI Version To install this extension, the Gemini CLI version must be v0.6.0 or above. The version can be found by running: `gemini --version`. -## BigQuery MCP Server (Data Plane: Connecting and Querying) +## BigQuery Skills (Data Plane: Connecting and Querying) + +This section covers connecting to BigQuery. + +1. **Extension Configuration**: This extension requires several settings (e.g., Project ID, Location). These values are gathered via prompts when you first install or link the extension: + + * `BIGQUERY_PROJECT`: The GCP project ID. + * `BIGQUERY_LOCATION`: (Optional) Location of the BigQuery resources. + + If you need to update any of these values later, use the `gemini extensions config bigquery-data-analytics` command. + +2. **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. + +3. **Handle Permission Errors**: + * For operations that execute queries and view metadata, the user needs the **BigQuery User** (`roles/bigquery.user`) and **BigQuery Metadata Viewer** (`roles/bigquery.metadataViewer`) role. + * For operations that create, or modify datasets and tables, the user needs the **BigQuery Data Editor** (`roles/bigquery.dataEditor`) role. + * If an operation fails due to permissions, identify the type of operation and recommend the appropriate role. You can provide these links for assistance: + * Granting Roles: https://cloud.google.com/iam/docs/grant-role-console + * BigQuery Permissions: https://cloud.google.com/iam/docs/roles-permissions/bigquery + +--- + +# Usage Guidelines + +## Reusing Project Values -This section covers connecting to a BigQuery instance. +Users may have set project environment variables: -1. **Verify Environment Variables**: Before attempting to connect, confirm with the user that the following environment variables are set in the extension configuration or their shell environment. +* `BIGQUERY_PROJECT`: The GCP project ID. +* `BIGQUERY_LOCATION`: (Optional) Location of the BigQuery resources. - * `BIGQUERY_PROJECT`: The GCP project ID. +Instead of prompting the user for these values for specific skill calls, prompt the user to verify the reuse of a specific setting value. +Make sure to not use the environment variable name like `BIGQUERY_PROJECT`, `${BIGQUERY_PROJECT}`, or `$BIGQUERY_PROJECT`. +The value can be verified by the user using the `gemini extensions config bigquery-data-analytics` command or by checking their local settings. -2. **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. +## Use Full Table Name Format "PROJECT.DATASET.TABLE" -3. **Handle Permission Errors**: - * For operations that execute queries and view metadata, the user needs the - **BigQuery User** (`roles/bigquery.user`) and **BigQuery Metadata Viewer** (`roles/bigquery.metadataViewer`) role. - * For operations that create, or modify datasets and tables, the user neds - the **BigQuery Data Editor** (`roles/bigquery.dataEditor`) role. - * If an operation fails due to permissions, identify the type of operation - and recommend the appropriate role. you can provide these links for - assistance: - * Granting Roles: https://cloud.google.com/iam/docs/grant-role-console - * BigQuery Permissions: - https://cloud.google.com/iam/docs/roles-permissions/bigquery +**ALWAYS** use the full table name format, `PROJECT.DATASET.TABLE` in the generated SQL when executing the `execute_sql` script. diff --git a/DEVELOPER.md b/DEVELOPER.md index c49d94c..02ac03e 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -16,7 +16,7 @@ Before you begin, ensure you have the following: ### Running from Local Source -The core logic for this extension is handled by a pre-built `toolbox` binary. The development process involves installing the extension locally into the Gemini CLI to test changes. +The development process involves installing the extension locally into the Gemini CLI to test changes. 1. **Clone the Repository:** @@ -25,29 +25,16 @@ The core logic for this extension is handled by a pre-built `toolbox` binary. Th cd bigquery-data-analytics ``` -2. **Download the Toolbox Binary:** The required version of the `toolbox` binary - is specified in `toolbox_version.txt`. Download it for your platform. - - ```bash - # Read the required version - VERSION=$(cat toolbox_version.txt) - - # Example for macOS/amd64 - curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/geminicli/v$VERSION/darwin/amd64/toolbox - chmod +x toolbox - ``` - Adjust the URL for your operating system (`linux/amd64`, `darwin/arm64`, `windows/amd64`). - -3. **Link the Extension Locally:** Use the Gemini CLI to install the +2. **Install the Extension Locally:** Use the Gemini CLI to install the extension from your local directory. ```bash - gemini extensions link . + gemini extensions install . ``` - The CLI will prompt you to confirm the linking. Accept it to proceed. + The CLI will prompt you to confirm the installation. Accept it to proceed. -4. **Testing Changes:** After linking, start the Gemini CLI (`gemini`). - You can now interact with the `bigquery-data-analytics` tools to manually test your changes +3. **Testing Changes:** After installing, start the Gemini CLI (`gemini`). + You can now interact with the `bigquery-data-analytics` skills to manually test your changes against your connected database. ## Testing @@ -76,13 +63,8 @@ are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/m ## Building the Extension The "build" process for this extension involves packaging the extension's -metadata files (`gemini-extension.json`, `bigquery-data-analytics.md`, `LICENSE`) along with the -pre-built `toolbox` binary into platform-specific archives (`.tar.gz` or `.zip`). - -This process is handled automatically by the -[`package-and-upload-assets.yml`](.github/workflows/package-and-upload-assets.yml) -GitHub Actions workflow when a new release is created. Manual building is not -required. +metadata files (`gemini-extension.json`, `BIGQUERY.md`, `LICENSE`) along with the +skills. ## Maintainer Information @@ -135,7 +117,3 @@ The process is handled by the [`mirror-changelog.yml`](.github/workflows/mirror- 2. **Merge Release PR:** A maintainer approves and merges the Release PR. This action triggers `release-please` to create a new GitHub tag and a corresponding GitHub Release. -3. **Package and Upload:** The new release triggers the - `package-and-upload-assets.yml` workflow. This workflow builds the - platform-specific extension archives and uploads them as assets to the - GitHub Release. diff --git a/README.md b/README.md index caa7b24..d05839d 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini * **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. +* **Run advanced analytics :** Generate forecasts, run a contributions analysis using built-in advanced skills. ## Prerequisites @@ -93,18 +93,12 @@ Interact with BigQuery using natural language right from your IDE: * "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 +## Supported Skills -This extension provides a comprehensive set of tools: +This extension provides a comprehensive set of skills: -* `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. +* `bigquery-data`: Use these skills when you need to handle large-scale data exploration and dataset management. Use when users need to find data assets or run SQL at scale. Provides metadata discovery and query execution across the data warehouse. +* `bigquery-analytics`: Use these skills when you need to handle advanced data intelligence and predictive tasks. Use when a user asks "why" data changed or needs future projections. Provides automated insight generation and time-series forecasting. ## Additional Extensions From 6557b3acdccc4e3ddbb9ef607e4908d84d0ad0c5 Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Tue, 14 Apr 2026 13:47:06 +0530 Subject: [PATCH 02/12] docs: add new optional bigquery settings to documentation --- BIGQUERY.md | 8 ++++++++ README.md | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/BIGQUERY.md b/BIGQUERY.md index 333c194..4186e6f 100644 --- a/BIGQUERY.md +++ b/BIGQUERY.md @@ -16,6 +16,10 @@ This section covers connecting to BigQuery. * `BIGQUERY_PROJECT`: The GCP project ID. * `BIGQUERY_LOCATION`: (Optional) Location of the BigQuery resources. + * `BIGQUERY_USE_CLIENT_OAUTH`: (Optional) Whether to use client OAuth (default: false). + * `BIGQUERY_SCOPES`: (Optional) Scopes for the BigQuery client. + * `BIGQUERY_MAX_QUERY_RESULT_ROWS`: (Optional) Maximum number of query result rows (default: 50). + * `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT`: (Optional) Service account to impersonate. If you need to update any of these values later, use the `gemini extensions config bigquery-data-analytics` command. @@ -38,6 +42,10 @@ Users may have set project environment variables: * `BIGQUERY_PROJECT`: The GCP project ID. * `BIGQUERY_LOCATION`: (Optional) Location of the BigQuery resources. +* `BIGQUERY_USE_CLIENT_OAUTH`: (Optional) Whether to use client OAuth (default: false). +* `BIGQUERY_SCOPES`: (Optional) Scopes for the BigQuery client. +* `BIGQUERY_MAX_QUERY_RESULT_ROWS`: (Optional) Maximum number of query result rows (default: 50). +* `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT`: (Optional) Service account to impersonate. Instead of prompting the user for these values for specific skill calls, prompt the user to verify the reuse of a specific setting value. Make sure to not use the environment variable name like `BIGQUERY_PROJECT`, `${BIGQUERY_PROJECT}`, or `$BIGQUERY_PROJECT`. diff --git a/README.md b/README.md index d05839d..6f555a9 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,10 @@ You will be prompted to configure the following settings during installation. Th * `BIGQUERY_PROJECT`: The GCP project ID. * `BIGQUERY_LOCATION`: (Optional) The dataset location. +* `BIGQUERY_USE_CLIENT_OAUTH`: (Optional) Whether to use client OAuth (default: false). +* `BIGQUERY_SCOPES`: (Optional) Scopes for the BigQuery client. +* `BIGQUERY_MAX_QUERY_RESULT_ROWS`: (Optional) Maximum number of query result rows (default: 50). +* `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT`: (Optional) Service account to impersonate. To view or update your configuration: @@ -65,6 +69,10 @@ Alternatively, you can manually set these environment variables before starting ```bash export BIGQUERY_PROJECT="" export BIGQUERY_LOCATION="" # Optional +export BIGQUERY_USE_CLIENT_OAUTH="false" # Optional +export BIGQUERY_SCOPES="" # Optional +export BIGQUERY_MAX_QUERY_RESULT_ROWS="50" # Optional +export BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT="" # Optional ``` > [!NOTE] From 1265ca257937ca405d4758a4368d3ba4820ceaaa Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Tue, 14 Apr 2026 13:58:27 +0530 Subject: [PATCH 03/12] small fix --- DEVELOPER.md | 2 +- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 74 insertions(+), 15 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index 02ac03e..ad78219 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -10,7 +10,7 @@ Before you begin, ensure you have the following: 1. **Gemini CLI:** Install the Gemini CLI version v0.6.0 or above. Installation instructions can be found on the official Gemini CLI documentation. You can verify your version by running `gemini --version`. -2. **BigQuery Access** For testing data plane tools, you will need access to an active BigQuery dataset. +2. **BigQuery Access** For testing data plane skills, you will need access to an active BigQuery dataset. ## Developing the Extension diff --git a/README.md b/README.md index 6f555a9..61f16ca 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@ 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). +[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]. @@ -13,6 +14,22 @@ Learn more about [Gemini CLI Extensions](https://github.com/google-gemini/gemini [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?](#why-use-the-bigquery-data-analytics-extension) +- [Prerequisites](#prerequisites) +- [Getting Started](#getting-started) + - [Gemini CLI](#gemini-cli) + - [Claude Code](#claude-code) + - [Codex](#codex) + - [Antigravity](#antigravity) +- [Usage Examples](#usage-examples) +- [Supported Skills](#supported-skills) +- [Additional Extensions](#additional-extensions) +- [Troubleshooting](#troubleshooting) + +--- + ## Why Use the BigQuery Data Analytics Extension? * **Natural Language to data analytics :** Find required BigQuery tables and ask analytical questions in natural language. @@ -33,15 +50,16 @@ Before you begin, ensure you have the following: ## Getting Started -### Installation +
+Gemini CLI -To install the extension, use the command: +To install the extension for Gemini CLI, use the command: ```bash gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics ``` -### Configuration +#### 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. @@ -62,7 +80,6 @@ To view or update your configuration: * 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: @@ -75,11 +92,7 @@ export BIGQUERY_MAX_QUERY_RESULT_ROWS="50" # Optional export BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT="" # 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 +#### Start Gemini CLI To start the Gemini CLI, use the following command: @@ -87,6 +100,52 @@ To start the Gemini CLI, use the following command: gemini ``` +
+ +
+Claude Code + +To use these skills with [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code): + +1. Navigate to your project directory. +2. Add the plugin: + ```bash + claude mcp add bigquery-data-analytics https://github.com/gemini-cli-extensions/bigquery-data-analytics + ``` +3. Claude will prompt you for the required configuration values. + +
+ +
+Codex + +To use these skills with [Codex](https://github.com/google-gemini/codex): + +1. Open the Codex interface. +2. Navigate to the **Extensions** or **Plugins** section. +3. Search for `bigquery-data-analytics` or provide the repository URL: `https://github.com/gemini-cli-extensions/bigquery-data-analytics`. +4. Follow the on-screen instructions to install and configure. + +
+ +
+Antigravity + +To use these skills with [Antigravity](https://github.com/google-gemini/antigravity): + +1. Install the skills using the Antigravity CLI: + ```bash + antigravity skills install https://github.com/gemini-cli-extensions/bigquery-data-analytics + ``` +2. Configure the environment variables as prompted or in your `.env` file. + +
+ +> [!NOTE] +> * Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. +> * See [Troubleshooting](#troubleshooting) for debugging your configuration. + + ## Usage Examples Interact with BigQuery using natural language right from your IDE: @@ -120,7 +179,7 @@ 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://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information. +* **"failed to find default credentials: google: could not find default credentials."**: Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/external/set-up-adc) 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://mcp-toolbox.dev/documentation/introduction/#install-toolbox) for more information. From bfe81794db5582c193334c72a9e5be6bbdc1cf64 Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 14:10:35 +0530 Subject: [PATCH 04/12] Update BIGQUERY.md --- BIGQUERY.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/BIGQUERY.md b/BIGQUERY.md index 4186e6f..b591f4e 100644 --- a/BIGQUERY.md +++ b/BIGQUERY.md @@ -1,7 +1,3 @@ -You are a highly skilled data engineer and data analyst. Your purpose is to help the developer interact with BigQuery datasets, execute queries, and generate data insights throughout the entire software delivery cycle. - ---- - # Setup ## Required Gemini CLI Version From 4dae00489b65c0885f01efecccd39b40920ef0ae Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 14:11:30 +0530 Subject: [PATCH 05/12] Update DEVELOPER.md --- DEVELOPER.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index ad78219..c3f69d6 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -46,7 +46,7 @@ for every pull request. This workflow primarily verifies that the extension can be successfully installed by the Gemini CLI. Currently, there are no automated unit or integration test suites -within this repository. All functional testing must be performed manually. All tools +within this repository. All functional testing must be performed manually. All skills are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/mcp-toolbox). ### Other GitHub Checks @@ -62,9 +62,8 @@ are currently tested in the [MCP Toolbox GitHub](https://github.com/googleapis/m ## Building the Extension -The "build" process for this extension involves packaging the extension's -metadata files (`gemini-extension.json`, `BIGQUERY.md`, `LICENSE`) along with the -skills. +The building process for this extension is handled automatically by the +automated workflows when a new release is created. Manual building is not required. ## Maintainer Information From 5133b54ba1bffab196e4abd779301643b8f3253b Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 14:12:16 +0530 Subject: [PATCH 06/12] Update README.md --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 61f16ca..987094c 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,6 @@ 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]. From 532eeb8a4e71af60d063a9a739cb0cfe350ac1fb Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 14:12:44 +0530 Subject: [PATCH 07/12] Update README.md --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 987094c..4c93ec9 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Developers can effortlessly connect, interact, and generate data insights with [ [form]: https://docs.google.com/forms/d/e/1FAIpQLSfEGmLR46iipyNTgwTmIDJqzkAwDPXxbocpXpUbHXydiN1RTw/viewform?usp=pp_url&entry.157487=bigquery-data-analytics ---- +## Table of Contents - [Why Use the BigQuery Data Analytics Extension?](#why-use-the-bigquery-data-analytics-extension) - [Prerequisites](#prerequisites) @@ -26,7 +26,6 @@ Developers can effortlessly connect, interact, and generate data insights with [ - [Additional Extensions](#additional-extensions) - [Troubleshooting](#troubleshooting) ---- ## Why Use the BigQuery Data Analytics Extension? From 6bec132890cdee7618e66275db7f632b0b6b5ee5 Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 14:14:16 +0530 Subject: [PATCH 08/12] Update README.md --- README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4c93ec9..4c544c9 100644 --- a/README.md +++ b/README.md @@ -38,12 +38,15 @@ Developers can effortlessly connect, interact, and generate data insights with [ 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`) +- One of these AI agents installed + - [Gemini CLI](https://github.com/google-gemini/gemini-cli) version **v0.6.0** or higher + - [Claude Code](https://claude.com/product/claude-code) version **v2.1.94** or higher + - [Codex](https://developers.openai.com/codex) **v0.117.0** or higher + - [Antigravity](https://antigravity.google) **v1.14.2** or higher +- 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 From 93f9e777bf39f9300c35500ca20a1f360dd39684 Mon Sep 17 00:00:00 2001 From: Twisha Bansal Date: Tue, 14 Apr 2026 14:20:55 +0530 Subject: [PATCH 09/12] update --- README.md | 176 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 125 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 4c544c9..6f4b47c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -# Gemini CLI Extension - BigQuery Data Analytics +# BigQuery Data Analytics Skills > [!NOTE] -> This extension is currently in beta (pre-v1.0), and may see breaking changes until the first stable release (v1.0). +> 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. @@ -50,18 +50,9 @@ Before you begin, ensure you have the following: ## Getting Started -
-Gemini CLI - -To install the extension for Gemini CLI, use the command: - -```bash -gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics -``` - -#### Configuration +### 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. +Please keep these env vars handy during the installation process: * `BIGQUERY_PROJECT`: The GCP project ID. * `BIGQUERY_LOCATION`: (Optional) The dataset location. @@ -70,77 +61,160 @@ You will be prompted to configure the following settings during installation. Th * `BIGQUERY_MAX_QUERY_RESULT_ROWS`: (Optional) Maximum number of query result rows (default: 50). * `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT`: (Optional) Service account to impersonate. -To view or update your configuration: +> [!NOTE] +> +> - Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. + +### Installation & Usage + +To start interacting with your database, install the skills for your preferred AI agent, then launch the agent and use natural language to ask questions or perform tasks. -**List Settings:** -* Terminal: `gemini extensions list` -* Gemini CLI: `/extensions list` +For the latest version, check the [releases page][releases]. -**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`. +[releases]: https://github.com/gemini-cli-extensions/bigquery-data-analytics/releases -Alternatively, you can manually set these environment variables before starting the Gemini CLI: + + +
+Gemini CLI + +**1. Install the extension:** ```bash -export BIGQUERY_PROJECT="" -export BIGQUERY_LOCATION="" # Optional -export BIGQUERY_USE_CLIENT_OAUTH="false" # Optional -export BIGQUERY_SCOPES="" # Optional -export BIGQUERY_MAX_QUERY_RESULT_ROWS="50" # Optional -export BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT="" # Optional +gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics ``` -#### Start Gemini CLI +During the installation, enter your environment vars as described in the [configuration section](#configuration). -To start the Gemini CLI, use the following command: +**2. (Optional) Manage Configuration:** +To view or update your configuration in Gemini CLI: + +- Terminal: `gemini extensions config bigquery-data-analytics [setting name] [--scope ]` +- Gemini CLI: `/extensions list` + +**3. Start the agent:** ```bash gemini ``` +_(Tip: Run `/extensions list` to verify your configuration and active extensions.)_ + +> [!WARNING] +> **Changing Instance & Database Connections** +> Currently, the database connection must be configured before starting the agent and can not be changed during a session. +> To save and resume conversation history in Gemini CLI use command: `/chat save ` and `/chat resume `. +
-Claude Code +Claude Code + +**1. Set env vars:** +In your terminal, set your environment vars as described in the [configuration section](#configuration). + +**2. Start the agent:** + +```bash +claude +``` + +**3. Add the marketplace:** + +```bash +/plugin marketplace add https://github.com/gemini-cli-extensions/bigquery-data-analytics.git#0.1.7 +``` + +**4. Install the plugin:** -To use these skills with [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code): +```bash +/plugin install bigquery-data-analytics@bigquery-data-analytics-marketplace +``` -1. Navigate to your project directory. -2. Add the plugin: - ```bash - claude mcp add bigquery-data-analytics https://github.com/gemini-cli-extensions/bigquery-data-analytics - ``` -3. Claude will prompt you for the required configuration values. +_(Tip: Run `/plugin list` inside Claude Code to verify the plugin is active, or `/reload-plugins` if you just installed it.)_
-Codex +Codex -To use these skills with [Codex](https://github.com/google-gemini/codex): +**1. Clone the Repo:** + +```bash +git clone --branch 0.1.7 git@github.com:gemini-cli-extensions/bigquery-data-analytics.git +``` + +**2. Install the plugin:** + +```bash +mkdir -p ~/.codex/plugins +cp -R /absolute/path/to/bigquery-data-analytics ~/.codex/plugins/bigquery-data-analytics +``` + +**3. Set env vars:** +Enter your environment vars as described in the [configuration section](#configuration). + +**4. Create or update marketplace.json:** +`~/.agents/plugins/marketplace.json` + +```json +{ + "name": "my-data-cloud-google-marketplace", + "interface": { + "displayName": "Google Data Cloud Skills" + }, + "plugins": [ + { + "name": "bigquery-data-analytics", + "source": { + "source": "local", + "path": "./plugins/bigquery-data-analytics" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Database" + } + ] +} +``` -1. Open the Codex interface. -2. Navigate to the **Extensions** or **Plugins** section. -3. Search for `bigquery-data-analytics` or provide the repository URL: `https://github.com/gemini-cli-extensions/bigquery-data-analytics`. -4. Follow the on-screen instructions to install and configure. +_(Tip: Run `codex plugin list` or use the `/plugins` interactive menu to verify your installed plugins.)_
-Antigravity +Antigravity -To use these skills with [Antigravity](https://github.com/google-gemini/antigravity): +**1. Clone the Repo:** -1. Install the skills using the Antigravity CLI: - ```bash - antigravity skills install https://github.com/gemini-cli-extensions/bigquery-data-analytics - ``` -2. Configure the environment variables as prompted or in your `.env` file. +```bash +git clone --branch 0.1.7 https://github.com/gemini-cli-extensions/bigquery-data-analytics.git +``` + +**2. Install the skills:** + +Choose a location for the skills: +- **Global (all workspaces):** `~/.gemini/antigravity/skills/` +- **Workspace-specific:** `/.agents/skills/` + +Copy the skill folders from the cloned repository's `skills/` directory to your chosen location: + +```bash +cp -R bigquery-data-analytics/skills/* ~/.gemini/antigravity/skills/ +``` + +**3. Set env vars:** +Set your environment vars as described in the [configuration section](#configuration). + +_(Tip: Antigravity automatically discovers skills in these directories at the start of a session.)_
+ + + > [!NOTE] > * Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. > * See [Troubleshooting](#troubleshooting) for debugging your configuration. From 9c40e6f5e5f1a62a8ccd47f589bcd0a690f20b4f Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 22:44:42 +0530 Subject: [PATCH 10/12] Update BIGQUERY.md --- BIGQUERY.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/BIGQUERY.md b/BIGQUERY.md index b591f4e..4b6fd27 100644 --- a/BIGQUERY.md +++ b/BIGQUERY.md @@ -12,10 +12,6 @@ This section covers connecting to BigQuery. * `BIGQUERY_PROJECT`: The GCP project ID. * `BIGQUERY_LOCATION`: (Optional) Location of the BigQuery resources. - * `BIGQUERY_USE_CLIENT_OAUTH`: (Optional) Whether to use client OAuth (default: false). - * `BIGQUERY_SCOPES`: (Optional) Scopes for the BigQuery client. - * `BIGQUERY_MAX_QUERY_RESULT_ROWS`: (Optional) Maximum number of query result rows (default: 50). - * `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT`: (Optional) Service account to impersonate. If you need to update any of these values later, use the `gemini extensions config bigquery-data-analytics` command. From 5c4ad1ca2234583923dbbcfe7f90aec70c5ab5e0 Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 22:45:14 +0530 Subject: [PATCH 11/12] Update BIGQUERY.md --- BIGQUERY.md | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/BIGQUERY.md b/BIGQUERY.md index 4b6fd27..b3611ed 100644 --- a/BIGQUERY.md +++ b/BIGQUERY.md @@ -23,26 +23,3 @@ This section covers connecting to BigQuery. * If an operation fails due to permissions, identify the type of operation and recommend the appropriate role. You can provide these links for assistance: * Granting Roles: https://cloud.google.com/iam/docs/grant-role-console * BigQuery Permissions: https://cloud.google.com/iam/docs/roles-permissions/bigquery - ---- - -# Usage Guidelines - -## Reusing Project Values - -Users may have set project environment variables: - -* `BIGQUERY_PROJECT`: The GCP project ID. -* `BIGQUERY_LOCATION`: (Optional) Location of the BigQuery resources. -* `BIGQUERY_USE_CLIENT_OAUTH`: (Optional) Whether to use client OAuth (default: false). -* `BIGQUERY_SCOPES`: (Optional) Scopes for the BigQuery client. -* `BIGQUERY_MAX_QUERY_RESULT_ROWS`: (Optional) Maximum number of query result rows (default: 50). -* `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT`: (Optional) Service account to impersonate. - -Instead of prompting the user for these values for specific skill calls, prompt the user to verify the reuse of a specific setting value. -Make sure to not use the environment variable name like `BIGQUERY_PROJECT`, `${BIGQUERY_PROJECT}`, or `$BIGQUERY_PROJECT`. -The value can be verified by the user using the `gemini extensions config bigquery-data-analytics` command or by checking their local settings. - -## Use Full Table Name Format "PROJECT.DATASET.TABLE" - -**ALWAYS** use the full table name format, `PROJECT.DATASET.TABLE` in the generated SQL when executing the `execute_sql` script. From c66a88639ed62b14cd468203473a742442ad4fdc Mon Sep 17 00:00:00 2001 From: Twisha Bansal <58483338+twishabansal@users.noreply.github.com> Date: Tue, 14 Apr 2026 22:46:24 +0530 Subject: [PATCH 12/12] Update README.md --- README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/README.md b/README.md index 6f4b47c..1af84ab 100644 --- a/README.md +++ b/README.md @@ -56,10 +56,7 @@ Please keep these env vars handy during the installation process: * `BIGQUERY_PROJECT`: The GCP project ID. * `BIGQUERY_LOCATION`: (Optional) The dataset location. -* `BIGQUERY_USE_CLIENT_OAUTH`: (Optional) Whether to use client OAuth (default: false). -* `BIGQUERY_SCOPES`: (Optional) Scopes for the BigQuery client. -* `BIGQUERY_MAX_QUERY_RESULT_ROWS`: (Optional) Maximum number of query result rows (default: 50). -* `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT`: (Optional) Service account to impersonate. + > [!NOTE] >