BigQuery Studio — User Manual

Welcome & Quick Start

Welcome to BigQuery Studio

BigQuery Studio is a native macOS client for Google BigQuery. It provides a fast, keyboard-driven interface for browsing datasets, writing SQL, and exporting results — all without leaving your desktop.

Application Layout

• Sidebar — Browse connections, datasets, tables, scripts, and favorites
• SQL Editor — Write and execute queries with syntax highlighting and autocomplete
• Results Panel — View query results in a sortable grid with JSON viewer for nested data
• Console — Monitor query execution, errors, and informational messages
• Status Bar — See connection status, row counts, and execution time

Quick Start

1. Set up a connection — Sign in with your Google account or import a Service Account JSON key
2. Browse your datasets — Expand projects and datasets in the sidebar to see tables and views
3. Write a query — Open a new tab (⌘T) and type your SQL in the editor
4. Execute — Press ⌘Return to run the query (or select text and press ⌘Return to run just the selection)
5. Export results — Click the export button to save results as CSV, JSON, Parquet, or other formats

Sign in with Google

The easiest way to connect is to sign in with your Google account. BigQuery Studio opens a secure Google sign-in window — your password never touches this app — and then lists every Google Cloud project you can access so you can pick one.

How It Works

1. Click "Add Connection" and choose "Sign in with Google" as the authentication method
2. A Google sign-in sheet opens (this is Google's own web UI, not ours)
3. Sign in and approve the requested permissions
4. BigQuery Studio fetches the list of projects you have access to and presents a Project Picker
5. Pick a project, click Save — you're connected

Permissions Requested

BigQuery Studio asks Google for three scopes:

• userinfo.email — so we can show who's signed in
• bigquery — read and write access to BigQuery queries, datasets, and jobs
• cloud-platform.read-only — needed to list projects in the Project Picker

Signing Out / Revoking Access

Inside a connection's edit sheet, click "Sign out" to delete the tokens from the Keychain and revoke them with Google. You can also revoke access any time from your Google Account dashboard.

Service Account Key

For production or automated workflows, you can authenticate using a Service Account JSON key file. This is useful when you need dedicated credentials separate from your personal Google account.

Setup Steps

1. Go to the Google Cloud Console → IAM & Admin → Service Accounts
2. Create a new service account (or select an existing one)
3. Grant the required BigQuery roles (see IAM Permissions section)
4. Create a JSON key: Actions → Manage Keys → Add Key → Create new key → JSON
5. Download the JSON key file to your machine
6. In BigQuery Studio, add a new connection and select "Service Account" as the authentication method
7. Click "Browse" to select your downloaded JSON key file
8. The project ID will be auto-detected from the key file

IAM Roles & Permissions

The following roles are required for BigQuery Studio to function correctly. Assign these to your user account or service account at the project level.

Required Roles

Optional Roles

Granting Roles

Ask your cloud administrator to grant these roles, or follow these steps in the Google Cloud Console:

1. Go to the Google Cloud Console → IAM & Admin → IAM
2. Click "Grant Access" at the top of the page
3. In the "New principals" field, enter the user's email or service account address
4. Under "Assign roles", add each required role
5. Click "Save" to apply the changes

Sidebar & Search

Use the search field at the top of the BigQuery tab to quickly locate any dataset, table, or view across all your loaded projects.

How It Works

• Start typing a name — the sidebar switches to a flat results list as you type
• Each result shows its full path as a breadcrumb (project → dataset → table)
• Matching datasets can be expanded in place to browse their tables
• Clear the search field to return to the full hierarchical tree

Context Menu Actions

Right-click any search result for the same actions available in the tree view:

• Open — Load the table's data or the dataset's contents
• Show in Tree — Jump back to the hierarchical view with the item selected
• Add to Favorites — Pin the item for quick access from the Favorites tab
• Properties — Open the Object or Dataset Properties sheet
• Data Quality — View Dataplex data quality scans (tables only)

SQL Editor

The SQL editor provides syntax highlighting, autocomplete for table and column names, and keyboard shortcuts for efficient query writing.

Executing Queries

• ⌘Return — Execute the full query in the current tab
• Select text + ⌘Return — Execute only the selected text
• ⌘. — Stop a running query

Editing Features

• ⌘⇧L — Format SQL (auto-indent and keyword alignment)
• ⌘/ — Toggle line comments (add or remove "-- " prefix)
• Remove All Comments — Strip all single-line and block comments (via menu)
• ⌘⇧D — Insert a query header with author name, date, and description

Tab Management

• ⌘T — Open a new query tab
• ⌘W — Close the current tab
• Tabs can be linked to saved scripts for automatic saving

Autocomplete

The editor provides autocomplete suggestions for table names and column names based on the datasets loaded in the sidebar. Start typing a name and press Tab or Return to accept a suggestion.

Results & Export

Query results are displayed in a sortable table. Click any column header to sort. Nested JSON/STRUCT fields can be expanded in the JSON viewer.

Data Export Formats

• CSV — Comma-separated values, compatible with Excel and most tools
• JSON — Structured JSON array with full nested data
• TSV — Tab-separated values
• Parquet — Columnar format for efficient analytics
• Avro — Row-based format with embedded schema

Schema Export Formats

• Avro Schema — .avsc JSON schema for Avro serialization
• JSON Schema — Standard JSON Schema for validation
• BigQuery Native — BigQuery JSON schema array for API use
• Terraform — HCL resource block for google_bigquery_table

Column Formatting

Customize how temporal and numeric columns are displayed in the results grid. Format presets are available in Settings and can be applied per-column from the column header menu.

HTML Report Export

Generate a self-contained HTML report that documents the schema of an entire project or dataset. Useful for sharing with stakeholders, onboarding new engineers, or archiving a snapshot before a migration.

Generating a Report

1. Right-click a project or dataset in the sidebar
2. Choose "Export HTML Report..."
3. Pick a destination folder
4. Watch the progress panel — the exporter reports phases
5. When finished, the report opens automatically in your default browser

What's Included

• Project or dataset overview (region, creation date, labels)
• Every table and view with its full schema, descriptions, and partitioning info
• Per-column data types, modes, and descriptions
• Search box at the top of the generated HTML for instant filtering
• Fully self-contained — no external CSS or JavaScript

Scripts Management

Save and organize your frequently used SQL queries as scripts. Scripts are stored locally and can be organized into folders.

Creating & Organizing

• Save a query as a script via ⌘S from any tab
• Create folders in the Scripts sidebar to organize your queries
• Drag and drop scripts between folders to reorganize
• Right-click a script or folder for rename, delete, and other options

Linking Tabs to Scripts

When you open a saved script, its tab becomes linked to that script. Any changes you make are automatically saved when you press ⌘S — no save dialog needed.

Import & Export

• ⌘⇧E — Export all scripts to a JSON file
• ⌘⇧I — Import scripts from a JSON file
• Export/Import individual folders from the context menu
• Full Backup — Export everything (scripts + favorites) to a single file

Favorites

Mark frequently accessed datasets, tables, and views as favorites for quick access from the sidebar.

Adding & Removing

• Right-click any dataset, table, or view in the sidebar and select "Add to Favorites"
• Right-click a favorite item and select "Remove from Favorites" to unmark it

Browsing Favorites

• Switch to the Favorites tab in the sidebar to see all your bookmarked items
• Favorites are grouped by type: Datasets, Tables, Views, and Scheduled Queries
• Expand a favorite dataset to browse its tables directly
• Use the search/filter field to quickly find a specific favorite

Scheduled Queries

BigQuery Studio surfaces all BigQuery Data Transfer Service scheduled queries for each connected project so you can review, filter, and inspect them without switching to the Cloud Console.

Opening the Scheduled Queries Tab

1. In the BigQuery sidebar, expand a project node
2. Click the "Scheduled Queries" entry
3. The main view switches to the Scheduled Queries table for that project

Filtering & Sorting

• Filter by status — enabled, disabled, or all
• Search by name, destination dataset, region, or owner
• Sort any column by clicking its header

Detail Sheet

Click any row to open the detail sheet, which shows the full configuration (SQL, destination, schedule, owner email, next run time) plus the recent run history with status and error messages.

Properties & Inspection

Object Properties

Inspect any table or view without running a query. Right-click a table or view in the sidebar and select "Properties".

• General tab — Full table ID, type, description, row count, size, partitioning, clustering, labels, and region
• Schema tab — Hierarchical column listing with nested STRUCT and REPEATED fields, data types, modes, and descriptions

Dataset Properties

Right-click a dataset and select "Properties" to see dataset ID, region, default table expiration, description, labels, and a searchable table list.

Job Lookup

Paste a BigQuery job ID to inspect its status and statistics. Open Job Lookup from the status bar (click the job ID of a recently executed query) or from the menu.

History & Usage

Query History

BigQuery Studio logs every query you execute locally. Toggle the Query History panel with ⌘⇧H.

• Each entry shows the SQL, project, execution time, row count, bytes processed, and status
• Filter by connection, status, or time range
• Search the SQL text to locate a specific query
• Double-click any entry to load the SQL into a new tab

Usage Dashboard

Open with ⌘⇧U to visualize your local query activity:

• Overview cards — total queries, bytes processed, estimated cost, failed queries
• Activity heatmap — day-of-week × hour-of-day grid
• Top projects and datasets by query count and bytes
• Filterable by time range (last 7 days, 30 days, all time)

Data Quality (Dataplex)

BigQuery Studio integrates with Google Cloud Dataplex to display data quality scan results for your tables. This requires the Dataplex Data Scans Viewer role.

Viewing Quality Scans

1. Right-click a table in the sidebar
2. Select "Data Quality" from the context menu
3. View scan results including rules, pass/fail scores, and job history

Quality Reports

• Export reports as Plain Text for quick sharing
• Export reports as PDF for formal documentation
• Reports include scan metadata, rule definitions, dimension scores, and job run history

Keyboard Shortcuts

All shortcuts use the Command (⌘) key as the primary modifier.

Settings

Access application settings from the menu bar: BigQuery Studio → Settings (or ⌘,).

Author Name

Set your name to be used in query headers inserted with ⌘⇧D. If left empty, "Anonymous" is used as the default.

Column Format Defaults

Configure default display formats for temporal and numeric columns in query results.

• Temporal — ISO 8601, US Date, European Date, Relative, Date Only, Time Only
• Numeric — Plain, Thousands, Compact (K/M/B), Percentage, Currency, Scientific

Troubleshooting

Error Modal

When something goes wrong, BigQuery Studio surfaces the problem in a global error modal with a clear title, friendly description, remediation hint, and full technical details. Click "Copy Details" to copy everything to your clipboard for sharing.

Common Problems

Sign-in sheet closes immediately — Usually caused by corporate SSO or workspace policies. Ask your Google Workspace admin to allow the BigQuery Studio OAuth client, or use Service Account authentication.

Selected the wrong Google account — Open the connection, click "Sign out", then "Sign in with Google" again to choose a different account.

Session expired — Open the affected connection and click "Sign in with Google" again to refresh your credentials.

Permission denied (403) — The account is missing an IAM role. See the IAM Permissions section for the required roles.

Quota exceeded (429) — Wait a minute and retry. Reduce bytes scanned with partition filters. Request a quota increase from the Cloud Console if persistent.

Invalid service account JSON — Re-download the key from the Cloud Console (IAM & Admin → Service Accounts → Keys) and re-import it.

What to Include When Reporting a Problem

1. The full error text from the modal — click "Copy Details" and paste it
2. The job ID from the status bar if the problem happened during query execution
3. The connection type (Google Sign-In vs. Service Account) and the project ID
4. A short description of what you were doing