# BigQuery

## Overview

Allow Suger to query and manage data in Google BigQuery.

Google BigQuery is a fully-managed, serverless, highly-scalable cloud data warehouse and analytics platform offered by Google Cloud Platform (GCP). It is designed to handle massive datasets and enable fast SQL queries using a pay-as-you-go pricing model.

By connecting Suger to Google BigQuery, you can build customized automation workflows for usage metering, financial reports, or notifications.

### Org-Level vs User-Level

> **Org-Level**: Uses a GCP service account for organization-wide BigQuery access. Best for company-wide data analytics.
>
> **User-Level**: Not applicable — BigQuery is an org-level integration only.

## Create Integration (Org-Level)

### Prerequisites

- GCP project with BigQuery API enabled
- Service account with BigQuery Admin role or appropriate dataset permissions

### Authenticate by Service Account

1. [Create a service account](https://cloud.google.com/iam/service-accounts-create) in your target GCP project for BigQuery service.
2. Grant appropriate BigQuery permissions to the service account. Some suggested options include:
   - BigQuery Admin
   - BigQuery User
   - BigQuery Data Viewer
3. [Create a service account key](https://cloud.google.com/iam/keys-create-delete#creating) and download the associated JSON file.
4. Enter the service account email and upload the JSON key in Suger.

## Suger AI Tools

Suger AI uses a **middleware** strategy — wrapping the BigQuery API directly.

> **Org-level only**: BigQuery tools use the org-level service account credentials.

| Tool | Description |
|------|-------------|
| `googlebigquery_list_datasets` | List all BigQuery datasets in the configured GCP project |
| `googlebigquery_list_tables` | List all tables in a BigQuery dataset |
| `googlebigquery_get_table_schema` | Get the schema (column names, types, descriptions) and metadata for a table |
| `googlebigquery_run_query` | Run a standard SQL query and return results |

## Edit Integration

Editing is not supported. To change configuration, delete and recreate.

## Delete Integration

Deleting removes the integration and revokes access. No recovery window.

:::warning
You must also remove the service account permissions in GCP Console.
:::