Google BigQuery

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

TablePro connects to BigQuery via its REST API. Browse datasets and tables, run GoogleSQL queries, edit rows in the data grid. The plugin auto-installs when you pick BigQuery, or install it from Settings > Plugins > Browse > BigQuery Driver.

Quick Setup

Click New Connection, select BigQuery, pick an auth method, enter your Project ID, and click Save & 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:

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

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.

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 chip in the toolbar, 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):

-- UNNEST arrays
SELECT id, tag
FROM `my_dataset.items`, UNNEST(tags) AS tag

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

Backtick-quote table names: `dataset.table`. Single-quote strings: 'value'.

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.

Query cost in the status bar after execution

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.

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.

DDL: Run DDL from the SQL editor: CREATE SCHEMA for datasets, ALTER TABLE ... ADD COLUMN and DROP COLUMN, CREATE OR REPLACE VIEW. The DDL tab reads each table’s definition from INFORMATION_SCHEMA.TABLES. The Structure tab is read-only for BigQuery.

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