diff --git a/BIGQUERY.md b/BIGQUERY.md index 6ee5c2f..b3611ed 100644 --- a/BIGQUERY.md +++ b/BIGQUERY.md @@ -4,24 +4,22 @@ 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 a BigQuery instance. +This section covers connecting to BigQuery. -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. +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_PROJECT`: The GCP project ID. + * `BIGQUERY_LOCATION`: (Optional) Location of the BigQuery resources. -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. + If you need to update any of these values later, use the `gemini extensions config bigquery-data-analytics` command. -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 +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 diff --git a/DEVELOPER.md b/DEVELOPER.md index c49d94c..c3f69d6 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -10,13 +10,13 @@ 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 ### 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 @@ -59,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 @@ -75,14 +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-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. +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 @@ -135,7 +116,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..1af84ab 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,10 @@ -# 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. -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,72 +12,211 @@ 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 +## Table of Contents + +- [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. * **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 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 -### Installation +### Configuration + +Please keep these env vars handy during the installation process: + +* `BIGQUERY_PROJECT`: The GCP project ID. +* `BIGQUERY_LOCATION`: (Optional) The dataset location. + -To install the extension, use the command: +> [!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. + +For the latest version, check the [releases page][releases]. + +[releases]: https://github.com/gemini-cli-extensions/bigquery-data-analytics/releases + + + +
+Gemini CLI + +**1. Install the extension:** ```bash gemini extensions install https://github.com/gemini-cli-extensions/bigquery-data-analytics ``` -### Configuration +During the installation, enter your environment vars as described in the [configuration section](#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. +**2. (Optional) Manage Configuration:** +To view or update your configuration in Gemini CLI: -* `BIGQUERY_PROJECT`: The GCP project ID. -* `BIGQUERY_LOCATION`: (Optional) The dataset location. +- 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 `. -To view or update your configuration: +
-**List Settings:** -* Terminal: `gemini extensions list` -* Gemini CLI: `/extensions list` +
+Claude Code -**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. +**1. Set env vars:** +In your terminal, set your environment vars as described in the [configuration section](#configuration). -Alternatively, you can manually set these environment variables before starting the Gemini CLI: +**2. Start the agent:** ```bash -export BIGQUERY_PROJECT="" -export BIGQUERY_LOCATION="" # Optional +claude ``` -> [!NOTE] -> * Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment. -> * See [Troubleshooting](#troubleshooting) for debugging your configuration. +**3. Add the marketplace:** -### Start Gemini CLI +```bash +/plugin marketplace add https://github.com/gemini-cli-extensions/bigquery-data-analytics.git#0.1.7 +``` -To start the Gemini CLI, use the following command: +**4. Install the plugin:** ```bash -gemini +/plugin install bigquery-data-analytics@bigquery-data-analytics-marketplace ``` +_(Tip: Run `/plugin list` inside Claude Code to verify the plugin is active, or `/reload-plugins` if you just installed it.)_ + +
+ +
+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" + } + ] +} +``` + +_(Tip: Run `codex plugin list` or use the `/plugins` interactive menu to verify your installed plugins.)_ + +
+ +
+Antigravity + +**1. Clone the Repo:** + +```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. + + ## Usage Examples Interact with BigQuery using natural language right from your IDE: @@ -93,18 +231,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 @@ -118,7 +250,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.