> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-feat-ai-sql-walkthroughs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Google BigQuery

> Connect to Google BigQuery with Service Account, ADC, or OAuth auth

# Google BigQuery Connections

TablePro connects to BigQuery via its REST API. Browse datasets and tables, run GoogleSQL queries, edit rows in the data grid. Plugin auto-installs or grab it from **Settings** > **Plugins** > **Browse**.

## Quick Setup

Click **New Connection**, select **BigQuery**, pick an auth method, enter your Project ID, connect.

## Authentication

**Service Account Key**: Point to a `.json` key file from Google Cloud Console (IAM > Service Accounts > Keys), or paste the raw JSON content directly into the field.

**Application Default Credentials**: Uses cached credentials from gcloud CLI. Supports `authorized_user`, `service_account`, and `impersonated_service_account` credential types. Run this first:

```bash theme={null}
gcloud auth application-default login --project=my-project
```

**Google Account (OAuth 2.0)**: Sign in with your Google account via browser. Requires an OAuth Client ID from your GCP project:

1. Go to [Google Cloud Console](https://console.cloud.google.com/) > APIs & Services > Credentials
2. Click "Create Credentials" > "OAuth client ID"
3. Select "Desktop app" as application type
4. Copy the Client ID and Client Secret into TablePro
5. On first connect, your browser opens for Google authorization
6. After approving, TablePro receives the token automatically

<Warning>
  Without a saved refresh token, the browser authorization repeats on every connect. Paste a refresh token into the **OAuth Refresh Token** field and TablePro mints access tokens from it instead of opening the browser. Application Default Credentials also persist.
</Warning>

## Connection Settings

| Field                   | Required   | Notes                                                                                                  |
| ----------------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| **Auth Method**         | Yes        | Service Account Key, ADC, or Google Account (OAuth)                                                    |
| **Project ID**          | Yes        | e.g. `my-project-123456`                                                                               |
| **Service Account Key** | SA only    | Path to `.json` key file, or raw JSON content                                                          |
| **OAuth Client ID**     | OAuth only | From GCP Console > APIs & Services > Credentials                                                       |
| **OAuth Client Secret** | OAuth only | From GCP Console > APIs & Services > Credentials                                                       |
| **OAuth Refresh Token** | No         | Optional. When set, access tokens are minted from it and the browser flow is skipped                   |
| **Location**            | No         | Processing location: `US`, `EU`, `us-central1`, etc.                                                   |
| **Max Bytes Billed**    | No         | Cost cap per query in bytes (Advanced tab). Queries exceeding this limit will fail instead of billing. |

## Features

**Dataset Browsing**: The sidebar lists every dataset as an expandable node. Click a dataset to load its tables; they load the first time you open it. Search filters across the datasets you have open.

**Dataset Switching**: Press `Cmd+K`, click the **Dataset** toolbar button, or use **File** > **Open Dataset...** to jump to another dataset. The switcher also creates new datasets (`Cmd+N` inside the popover) and drops datasets from the row context menu.

**Table Structure**: Columns with full BigQuery types: `STRUCT<name STRING, age INT64>`, `ARRAY<STRING>`, nullable status, field descriptions. Clustering and partitioning info in the Indexes tab.

**GoogleSQL Queries** ([docs](https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax)):

```sql theme={null}
-- UNNEST arrays
SELECT id, tag
FROM `my_dataset.items`, UNNEST(tags) AS tag

-- STRUCT access
SELECT address.city FROM `my_dataset.customers`
```

<Tip>
  Backtick-quote table names: `` `dataset.table` ``. Single-quote strings: `'value'`.
</Tip>

**Query Cost**: After running a query in the SQL editor, the status bar shows bytes processed, bytes billed, and estimated cost (e.g., `Processed: 1.5 MB | Billed: 10 MB | ~$0.0001`). Use the **Dry Run** option (Explain dropdown > "Dry Run (Cost)") to check cost before executing.

<Frame caption="Query cost in the status bar after execution">
  <img className="block dark:hidden" src="https://mintcdn.com/ngquct-feat-ai-sql-walkthroughs/REI9tfF_TGivM099/images/bigquery-query-cost.png?fit=max&auto=format&n=REI9tfF_TGivM099&q=85&s=ede562e8b85e2b96afb2966da8539168" alt="Status bar showing bytes processed, bytes billed, and estimated query cost" width="1560" height="960" data-path="images/bigquery-query-cost.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/ngquct-feat-ai-sql-walkthroughs/REI9tfF_TGivM099/images/bigquery-query-cost-dark.png?fit=max&auto=format&n=REI9tfF_TGivM099&q=85&s=cfca518b1d39daaed374ff6ba244c5b9" alt="Status bar showing bytes processed, bytes billed, and estimated query cost" width="1560" height="960" data-path="images/bigquery-query-cost-dark.png" />
</Frame>

**Data Types**: INT64, FLOAT64, NUMERIC, BIGNUMERIC, BOOL, STRING, BYTES, DATE, TIME, DATETIME, TIMESTAMP, GEOGRAPHY, JSON, STRUCT, ARRAY, RANGE. Complex types (STRUCT/ARRAY) display as JSON.

**Data Editing**: Edit cells, insert rows, and delete rows in the data grid.

<Warning>
  Partitioned tables require a partition filter for UPDATE/DELETE. Every query costs money (billed per bytes scanned). Set **Max Bytes Billed** in Advanced settings to cap costs.
</Warning>

**DDL**: Create datasets (`CREATE SCHEMA`), add/drop columns (`ALTER TABLE`), create views (`CREATE OR REPLACE VIEW`). Table DDL viewable via INFORMATION\_SCHEMA.

**Export**: CSV, JSON, SQL, XLSX formats.

## IAM Permissions

Minimum roles:

* `roles/bigquery.user` -- run queries
* `roles/bigquery.dataViewer` -- browse and read data
* `roles/bigquery.dataEditor` -- INSERT, UPDATE, DELETE

## Troubleshooting

**Auth failed**: Check key file path or run `gcloud auth application-default login`.

**Permission denied**: Ensure `bigquery.user` role is granted on the project.

**Project not found**: Use the Project ID (not name or number).

**Query timeout**: BigQuery runs jobs async. The plugin polls up to 5 minutes (configurable).

**Cost**: Use `LIMIT`, select specific columns, prefer partitioned tables. Set **Max Bytes Billed** to prevent expensive queries. Table browsing caps rows automatically.

**No tables after connect**: Expand a dataset node in the sidebar to load its tables. Empty datasets stay empty; open another dataset that has tables.

## Limitations

* No SSH tunneling (HTTPS only to BigQuery API)
* No transactions
* STRUCT/ARRAY columns excluded from UPDATE/DELETE WHERE clauses
* Deep pagination (large OFFSET) scans from start. Use filters to narrow results
* No streaming inserts
* Browser OAuth re-authorizes on each connect unless a refresh token is saved in the connection