BigQuery Studio for Visual Studio Code

Fork Notice: This extension is a fork of bstruct/vscode-bigquery with additional improvements and fixes.

A powerful Visual Studio Code extension for Google BigQuery. Browse datasets and tables, run queries with real-time validation, view results, format SQL, track query history, estimate costs, and visualize data lineage.

What's Different

This fork includes the following improvements over bstruct/vscode-bigquery:

New Features

• Smart Column Autocomplete - Type alias. or cte_name. to get column suggestions from tables and CTEs
• Data Lineage Visualization - dbt-style lineage graphs with CTE support, multi-query support, click-to-navigate, hover tooltips, Query Result nodes, and right-click lineage for selection
• Query History - Track all executed queries with re-run and copy capabilities
• Table Schema Hover - Hover over table names to see schema details (supports JOINs, CTEs, and backtick-quoted identifiers)
• Cost Estimator - Real-time query cost estimates with configurable $/TB pricing
• SQL Formatter - Advanced formatting with leading commas, keyword casing, indent styles, and more options
• Copy to Clipboard - Copy query results directly to clipboard with configurable size limits
• Schema Refresh Command - Clear cached table schemas when they become outdated

Improvements

• Offline-Ready Charting - MorphCharts bundled locally instead of CDN for air-gapped environments
• Enhanced SQL Intellisense - 400+ keywords/functions with syntax highlighting (including ALL, ANY, SOME)
• Block Comment Support - Full /* */ syntax highlighting and code folding
• Windows Support - Fixed gcloud authentication issues on Windows
• Security Hardening - XSS prevention, Content Security Policy, and input validation
• Better Panel State - Webview panels retain context when hidden
• Auto-Reveal Control - Setting to disable automatic results panel focus switching

Features

• Authentication - User login, GDrive access, and service account support via gcloud CLI
• Project Explorer - Browse projects, datasets, tables, views, functions, and ML models
• Query Execution - Run queries with Ctrl+Enter, real-time error highlighting, and byte estimation
• SQL Intellisense - Autocomplete for SQL keywords, BigQuery functions, and table/CTE columns
• Syntax Highlighting - Full support for .bqsql files with grammar injection for .sql files
• SQL Formatting - Format queries with configurable style options
• Query History - Track all executed queries with re-run and copy capabilities
• Cost Estimation - Real-time cost estimates based on bytes processed
• Table Schema Hover - Hover over table names to see schema details
• Data Lineage - Visualize data flow with CTE support
• Export Options - Download results as CSV or JSONL, copy to clipboard
• Pub/Sub Integration - Publish query results directly to Google Cloud Pub/Sub

Installation

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "BigQuery Studio"
4. Click Install

Or install from the VS Code Marketplace.

Requirements

• Google Cloud SDK (gcloud CLI) must be installed
• Valid Google Cloud authentication with BigQuery permissions

Quick Start

1. Install the gcloud CLI and authenticate: gcloud auth login
2. Open the BigQuery panel from the Activity Bar
3. Create a new .bqsql file and write your query
4. Press Ctrl+Enter to run

Keyboard Shortcuts

Shortcut	Icon	Command	Description
Ctrl+Enter		Run Query	Execute the entire query in the editor
Ctrl+E		Run Selected Query	Execute only the selected text
Shift+Alt+F		Format SQL	Format the current SQL document

Command Palette

All commands are available via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P). Type "BigQuery" to see all available commands:

Authentication

The extension uses the gcloud CLI for authentication. Three authentication methods are supported:

• User login - Opens browser for Google Cloud authentication
• User login + GDrive - Same as above, with Google Drive access for Drive-based tables
• Service account - Select a service account key file (JSON format)

When there's a valid account active with BigQuery permissions, the extension is ready to use.

Additional functionality:

• Activate/switch between multiple accounts
• Revoke authentication

Refresh the authentication screen with the command BigQuery: Authentication refresh.

Projects, Datasets, and Tables Explorer

The BigQuery side panel displays a tree of projects, datasets, tables, views, functions, and ML models.

Refresh the explorer with the command BigQuery: Explorer refresh.

You can set a default project that queries will run against by right-clicking on a project.

Context Menu Actions

Right-click on tables and views to access:

• Create query - Opens a new editor with a basic SELECT * FROM statement
• Open DDL - Opens the DDL (Data Definition Language) statement for the object
• Preview - Opens a preview of the table data (runs SELECT * for views and external tables)
• Preview schema - Opens the table/view schema information

Table Preview

Schema View

Run Queries

The extension activates for .bqsql files. Run queries using:

• Keyboard: Ctrl+Enter (run all) or Ctrl+E (run selected)
• Command Palette: BigQuery: Run Query or BigQuery: Run Selected Query
• Editor Toolbar: Click the run buttons

Query results appear in the bottom panel under Bigquery: Query results. You can open results in a separate tab for side-by-side comparisons.

Syntax Highlighting & Intellisense

The extension provides:

• Syntax highlighting for SQL keywords (SELECT, FROM, WHERE, JOIN, CASE, WHEN, etc.)
• Block comment support (/* */) with syntax highlighting and folding
• Intellisense/autocomplete for SQL keywords and BigQuery functions
• Grammar injection for .sql files (syntax highlighting works automatically)

Smart Column Autocomplete

Type . after a table alias, CTE name, or table reference to get column suggestions:

• CTE columns - Type cte_name. to see columns defined in the CTE's SELECT clause
• Table alias columns - Type alias. to see columns from the aliased table (resolves aliases automatically)
• Physical table columns - Type `project.dataset.table`. to see columns from BigQuery tables (schema must be cached first via hover)
• Column priority - Columns appear at the top of the autocomplete list, above functions and keywords

The autocomplete works during active typing even when SQL is incomplete, using regex fallback parsing when the full parser fails.

Real-time Query Validation

Queries are validated as you type. Errors are underlined in the editor:

Valid queries show the estimated bytes in the status bar:

Query History

All executed queries are saved to the History panel in the BigQuery sidebar.

Each history entry shows:

• Query preview text
• Execution timestamp
• Bytes processed and duration
• Success/error status

Right-click actions:

• Re-run - Execute the query again
• Copy - Copy query text to clipboard
• Delete - Remove from history

Use the clear button to remove all history entries.

Cost Estimator

The status bar shows real-time cost estimates based on BigQuery's dry-run feature:

• Estimated bytes to be processed
• Estimated cost in USD (configurable, default $6.25/TB)

Configure the cost per TB in settings via vscode-bigquery.costPerTB. Set to 0 to hide cost estimates:

Table Schema Hover

Hover over any table name in your SQL query to see schema information:

• Column names and data types
• Column descriptions (if available)
• Partitioning and clustering information

The schema is cached after first fetch for faster subsequent lookups.

Refresh Schema Cache

If a table schema has changed in BigQuery, the cached schema may be outdated. To clear the cache and fetch fresh schemas:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Run BigQuery: Refresh Schema Cache

This clears all cached schemas. The next time you hover over a table, fresh schema data will be fetched from BigQuery.

Supported Locations

Schema hover works for tables in:

• FROM clauses - FROM project.dataset.table
• JOIN clauses - JOIN project.dataset.table, LEFT JOIN, RIGHT JOIN, INNER JOIN, CROSS JOIN, FULL JOIN
• CTE references - When you reference a CTE name (e.g., FROM my_cte), the hover shows the columns defined in that CTE's SELECT clause

Data Lineage

Visualize data flow in your queries. Click the lineage button in the editor title bar (top-right corner) or run BigQuery: Show Data Lineage.

The lineage graph shows:

• Source tables (blue) - Tables your query reads from
• CTEs (purple) - Common Table Expressions as intermediate nodes
• Target tables (green) - Tables your query writes to (INSERT, CREATE, MERGE, etc.)
• Query Result (orange) - Destination node for SELECT-only queries

Features:

• Multi-Query Support - Files with multiple queries show separate lineage diagrams stacked vertically
• Collapsible Query Sections - Each query section has collapse/expand toggles with chevron icons for easier navigation
• Lineage for Selection - Right-click on selected SQL text to generate lineage for just that portion
• Click to Navigate - Click on any node to jump to its location in the SQL source code
• Hover Tooltips - Hover over nodes to see the full qualified table name
• CTE Support - CTEs are shown as intermediate nodes between sources and targets
• Layered DAG Layout - Nodes are arranged left-to-right based on data flow
• Curved Connections - Bezier curves show relationships between nodes (curves around overlapping edges)
• Statement Type Badges - Target nodes show the operation type
• Zoom Controls - Zoom in/out and reset buttons, plus Ctrl+scroll wheel support

Exporting Lineage Charts

Export lineage visualizations to share, document, or print your data pipelines:

• PNG Export - Click "↓ PNG" to save as high-quality image (2x resolution)

  • Ideal for embedding in wikis, documentation, or presentations
  • Preserves VS Code theme colors and styling

• PDF Export - Click "↓ PDF" to save as vector PDF

  • Perfect for printing or sharing with stakeholders
  • Maintains quality at any zoom level

• Multi-Query Files - Files with multiple queries show additional export options:

  • Individual export - Click PNG/PDF button on each query section
  • Bulk export - Click "↓ All PNG" (separate files) or "↓ All PDF" (multi-page document) in the header

• File Naming - Files are automatically named with:

  • Query number (for multi-query files)
  • Line range (e.g., lines1-15)
  • Timestamp (e.g., 20260102_143052)
  • Example: lineage_query1_lines1-15_20260102_143052.png

• Export Theme - Switch between dark and light themes for exports:

  • Dark theme (default) - Dark background with light text
  • Light theme - White background with dark text (better for printing)
  • Toggle via Command Palette: BigQuery: Toggle Lineage Export Theme
  • Or configure in settings: vscode-bigquery.lineageExportTheme

Exported files include the complete lineage graph with proper node colors, edges, and layout.

Note: Lineage requires valid SQL. If your query contains syntax errors, the lineage graph may be incomplete or unavailable.

Format SQL

Format your BigQuery SQL queries with Shift+Alt+F or by running BigQuery: Format SQL.

Configuration options:

Export Options

Download CSV

After running a query, download results as CSV from the result grid toolbar.

• Supports multiline content
• No row limit (be mindful of large result sets)
• Does not support nested complex objects

Copy to Clipboard

Copy results in CSV format with a configurable size limit (default 1MB). Configure via vscode-bigquery.clipboardSizeLimitKb.

Download JSONL

Download results in JSONL format from the result grid toolbar.

Send to Pub/Sub

Publish query results to Google Cloud Pub/Sub (one message per row).

Requirements:

• A column named data of type STRING or JSON
• Optional: A column named attributes of type RECORD

Example query:

SELECT
    (
    SELECT AS STRUCT
        "my test test" AS test,
        "amazing data type" AS data_type
    ) AS attributes,

    TO_JSON(t) AS data

FROM `dataset.table` t

Enter the topic name in the format: projects/<project_id>/topics/<topic_name>

Settings

Pin a Project

Pin projects to keep them at the top of the explorer tree.

Pinned projects are stored in settings:

Hide a Project

Hide projects from the explorer tree to reduce clutter. Hidden projects can be restored at any time.

To hide a project:

• Right-click on a project in the explorer and click the "Hide" button (eye-closed icon)

To unhide a project:

• Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
• Run BigQuery: Show Hidden Projects
• Select the project to unhide from the list

Alternatively, you can manage hidden projects directly in settings via vscode-bigquery.hidden-projects.

Add GCP Projects

For cases where you only have read permissions at the dataset level (not project level), force a project to be listed:

Setting: vscode-bigquery.projects

Add BigQuery Tables

When permission is granted only at the table level:

Setting: vscode-bigquery.tables

Associate .sql Files

Enable BigQuery features for all .sql files:

Setting: vscode-bigquery.associateSqlFiles

Configuration Reference

Access settings via:

Troubleshooting

Query results panel not opening

Sometimes after installation, the BigQuery: Run query command doesn't open the results panel. Restart VS Code to resolve this.

Authentication issues

Ensure the gcloud CLI is properly installed and you've run gcloud auth login successfully.

Missing projects or datasets

If you have limited permissions, add projects or tables manually via settings.

Report a Bug

Please file an issue with as much detail as possible at GitHub Issues.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the original project bstruct/vscode-bigquery for license details.