Skip to main content
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 driver is not in the app. Picking in the Choose a Database sheet offers the download before the form opens, and opening a saved connection installs it without asking. Settings > Plugins > Browse > installs it up front. See Plugins.

​
Quick setup

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

​
Connection settings

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.

​
Authentication

​
Application default credentials

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)

1

Create a desktop OAuth client

In Google Cloud Console, under APIs & Services > Credentials, click Create Credentials > OAuth client ID and pick Desktop app.
2

Copy it into TablePro

Paste the Client ID and Client Secret into the connection form.
3

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.
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.

​
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.25perTB:‘Processed:1.5MB∣Billed:10MB∣ 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.
Status bar showing bytes processed, bytes billed, and estimated query cost

Query cost in the status bar after execution

​
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, 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.