> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-docs-fix-500-query-results.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

export const name_0 = "BigQuery"

export const plugin_0 = "BigQuery Driver"

Use Application Default Credentials if `gcloud` is already on the machine. The other two methods are for machines where it is not: a service account key file, or a browser sign-in against an OAuth client you create. Everything travels over the REST API, so there is no host, port, or tunnel.

The {name_0} driver is not in the app. Picking {name_0} in the **Choose a Database** sheet offers the
download before the form opens, and opening a saved {name_0} connection installs it without asking.
**Settings > Plugins > Browse > {plugin_0}** installs it up front. See [Plugins](/features/plugins).

## Quick setup

Click **Create Connection…**, select **BigQuery**, pick an auth method, enter your Project ID, and click **Save & Connect**.

## Connection settings

| Field                                        | Required             | Notes                                                                           |
| -------------------------------------------- | -------------------- | ------------------------------------------------------------------------------- |
| **Auth Method**                              | Yes                  | Service Account Key, Application Default Credentials, or Google Account (OAuth) |
| **Project ID**                               | Yes                  | The ID (`my-project-123456`), not the name or number                            |
| **Service Account Key**                      | Service account only | A `.json` key file path, or the raw JSON                                        |
| **OAuth Client ID**, **OAuth Client Secret** | OAuth only           | From GCP Console > APIs & Services > Credentials                                |
| **OAuth Refresh Token**                      | No                   | Set it and the browser flow is skipped                                          |
| **Location**                                 | No                   | Processing location (`US`, `EU`, `us-central1`), sent with every job            |
| **Max Bytes Billed**                         | No                   | Advanced tab. A query over the cap fails instead of billing                     |

There is no Database field and no URL scheme. Datasets stand in for databases: the sidebar lists them as expandable nodes, `Cmd+K` and **Database > Open Database…** move between them, and **Database > New Database…** runs `CREATE SCHEMA`. Switching does not move tabs you already have open; each stays on its own dataset. See [Tabs](/features/tabs#where-a-tab-points).

## Authentication

### Application default credentials

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

The driver reads `~/.config/gcloud/application_default_credentials.json`, accepting the `authorized_user`, `service_account`, and `impersonated_service_account` types. The form then needs only a Project ID.

### Service account key

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

### Google account (OAuth 2.0)

<Steps>
  <Step title="Create a desktop OAuth client">
    In [Google Cloud Console](https://console.cloud.google.com/), under APIs & Services > Credentials, click Create Credentials > OAuth client ID and pick Desktop app.
  </Step>

  <Step title="Copy it into TablePro">
    Paste the Client ID and Client Secret into the connection form.
  </Step>

  <Step title="Authorize in the browser">
    On connect your browser opens Google's consent screen, and the token arrives on an ephemeral loopback redirect. The step times out after two minutes.
  </Step>
</Steps>

<Warning>
  The refresh token from a browser sign-in is held in memory only, so the browser opens again on every connect. Paste a refresh token into **OAuth Refresh Token** to mint access tokens from it instead.
</Warning>

## Cost

Every query is billed on bytes scanned, so there are three places to control it.

* Before running, pick **Dry Run (Cost)** from the Explain dropdown. It asks BigQuery what the query would scan without executing it.
* After running, the status bar shows bytes processed, bytes billed, and an estimate at the on-demand rate of $6.25 per TB: `Processed: 1.5 MB | Billed: 10 MB | ~$0.0001`. A cache hit is marked `(cached)\`.
* As a hard ceiling, set **Max Bytes Billed**: BigQuery rejects a job that would exceed it.

<Frame caption="Query cost in the status bar after execution">
  <img className="block dark:hidden" src="https://mintcdn.com/ngquct-docs-fix-500-query-results/hA72m8tSnRe3b-ew/images/bigquery-query-cost.png?fit=max&auto=format&n=hA72m8tSnRe3b-ew&q=85&s=01bdfd8dbdf8348a183089d20492eeda" 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-docs-fix-500-query-results/hA72m8tSnRe3b-ew/images/bigquery-query-cost-dark.png?fit=max&auto=format&n=hA72m8tSnRe3b-ew&q=85&s=4772cc19e2f94e2fe96e26186c9d4b53" 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>

## Querying and editing

Completion, quoting, and formatting follow GoogleSQL: backticks around table names, single quotes around strings. `STRUCT` and `ARRAY` columns display as JSON. Cells, inserts, and deletes go through the grid. The Structure tab is read-only, but DDL runs from the editor: `CREATE SCHEMA`, `ALTER TABLE … ADD COLUMN` and `DROP COLUMN`, `CREATE OR REPLACE VIEW`. The DDL tab reads definitions from `INFORMATION_SCHEMA.TABLES`; clustering and partitioning appear under Indexes.

Minimum IAM roles: `roles/bigquery.user` to run queries, `roles/bigquery.dataViewer` to read, `roles/bigquery.dataEditor` to write.

## Limitations

* `STRUCT` and `ARRAY` columns are left out of a generated UPDATE or DELETE's `WHERE` clause. A row identified only by one of them cannot be edited from the grid.
* A partitioned table needs a partition filter for UPDATE and DELETE, or the statement is rejected. Write it in the editor.
* No transactions, no streaming inserts, no SSH tunnel.
* Deep pagination rescans from the start of the table. Filter rather than paging far in.
* A job is polled until the [query timeout](/customization/general-settings#query-timeout), then cancelled. The floor is 30 seconds, so **No limit** gives BigQuery 30 seconds rather than none.

## Troubleshooting

**Application default credentials not found at \~/.config/gcloud/application\_default\_credentials.json**: Run `gcloud auth application-default login`, or switch the connection to a service account key.

**Permission denied**: Authenticated but unauthorized. Grant `roles/bigquery.user` on the project and a data role on the dataset.

**Project not found**: Enter the Project ID, not the display name and not the numeric project number.

**No tables after connect**: Tables load when you expand the dataset node. An empty dataset stays empty; open another.