Skip to content
kitagryPublic

About

BigQuery language server

Topics

Resources

Stars

50 stars

Watchers

2 watching

Forks

Repository files navigation

bqls

The BigQuery Language Server

Completion, hover, lint, and query execution for BigQuery SQL, right in your editor.

build and test govulncheck Release Go version VS Code Marketplace License

Features • Quick Start • Editor Setup • Lint • Save Result • Supported Protocol

bqls in Neovim: completion, hover, a lint quick fix, a dry-run cost estimate, and query results; then bqls lint in a terminal: findings, --fix, a clean rerun, and a dry-run cost check

✨ Features

Feature What you get
💡 Completion Projects, datasets, tables, columns, DECLARE variables, keywords, and built-in functions, using your real BigQuery schemas
📖 Hover Table schemas and metadata, column types and descriptions, and built-in function docs
🎯 Go to definition Jump to CTEs and aliases, or open a table's details as a virtual document
🩺 Diagnostics Analysis errors from the GoogleSQL analyzer as you type, checked against your table schemas
💰 Dry-run cost estimate "This query will process 1.25 GiB when run." on save, before you spend anything
🧹 Lint 43 rules for correctness, cost, and unused code, with quick fixes, bqls:ignore comments, a shared .bqls.yaml, and the bqls lint CLI for CI (docs)
🎨 Formatting Format BigQuery SQL with the GoogleSQL formatter
▶️ Query execution Run or cancel queries and view the results in the editor (bqls.executeQuery)
🗂️ Explore Browse datasets, tables, and job histories (bqls.listDatasets, bqls.listTables, bqls.listJobHistories)
📊 Save to Sheets Export query results to Google Sheets (bqls.saveResult, see Save Result)

🚀 Quick Start

1. Install

Download the latest binary for Linux or macOS (amd64 / arm64) from GitHub Releases and put it in your PATH, or install it with Go:

go install github.com/kitagry/bqls@latest

2. Log in to use the BigQuery API

gcloud auth login
gcloud auth application-default login

If the credentials are missing or expire later, bqls shows this guidance instead of a raw BigQuery error. After you log in again, bqls picks up the new credentials without a restart.

3. Set up your editor

  • Neovim: install bqls.nvim and call require("lspconfig").bqls.setup({}). See Neovim.
  • VSCode: install the bqls extension. It downloads bqls for you on macOS and Linux. See VSCode.

Build from source

Prerequisites: Go 1.26 or later.

git clone https://github.com/kitagry/bqls.git
cd bqls
go install

⚙️ Editor Setup

Neovim

You can use bqls.nvim to integrate BigQuery with Neovim.

You can specify your BigQuery Project ID and location in the configuration. If not specified, the plugin will use gcloud config get project for the Project ID and US as the default location.

require("lspconfig").bqls.setup({
  settings = {
    project_id = "YOUR_PROJECT_ID",
    location = "YOUR_LOCATION",
  },
})
Change settings at runtime with workspace/didChangeConfiguration

You can change project_id with workspace/didChangeConfiguration.

vim.lsp.buf_notify(0, "workspace/didChangeConfiguration", { settings = { project_id = "ANOTHER_PROJECT_ID", location = "ANOTHER_LOCATION" } })

Settings omitted from the notification keep their current values, so you can send only what changed. A lint setting, when sent, replaces the whole rule set; lint = vim.empty_dict() or lint = vim.NIL restores the defaults (a plain {} is encoded as a JSON array and rejected).

Async virtual text documents (for client authors)

bqls also supports fetching virtual document previews (table/job info) asynchronously so the client isn't blocked while BigQuery is queried; see bqls/publishVirtualTextDocument in the API reference. This is opt-in via supports_async_virtual_text_document in initializationOptions, so bqls.nvim keeps working unmodified until it adopts the new flow.

VSCode

The official VSCode extension lives in editors/vscode in this repository and is published on the Visual Studio Marketplace. See its README for settings such as bqls.projectId, bqls.location, and bqls.lint.rules.

You can also use the community extension bqls-vscode.

Lint

bqls reports lint findings (e.g. comparisons with NULL, missing partition filters, unused CTEs) as diagnostics for queries that analyze without errors, with quick fixes for some rules. bqls lint runs the same rules from the command line, e.g. in CI, and a .bqls.yaml shares the settings between your editor and CI.

$ bqls lint --project my-project queries/
queries/report.sql:3:6: info: CTE `tmp` is defined but never used (unused-cte)

See docs/lint.md for the list of rules, configuration, and the CLI.

Save Result

In order to save for spreadsheet, you should enable Google Drive API.

  1. Enable Google Drive API and Google Sheets API
  2. gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/drive

Supported Protocol

License

Apache License 2.0

About

BigQuery language server

Topics

Resources

Stars

50 stars

Watchers

2 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages