The BigQuery Language Server
Completion, hover, lint, and query execution for BigQuery SQL, right in your editor.
Features • Quick Start • Editor Setup • Lint • Save Result • Supported Protocol
| 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) |
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@latest2. Log in to use the BigQuery API
gcloud auth login
gcloud auth application-default loginIf 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
bqlsfor 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 installYou 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.
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.
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.
In order to save for spreadsheet, you should enable Google Drive API.
- Enable Google Drive API and Google Sheets API
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/drive
- textDocument/formatting
- textDocument/hover
- textDocument/completion
- textDocument/definition
- textDocument/codeAction
- workspace/executeCommand
- bqls.executeQuery
- bqls.cancelQuery
- bqls.listProjects
- bqls.listDatasets
- bqls.listTables
- bqls.searchTables
- bqls.listJobHistories
- bqls.saveResult
- bqls.listProjects
- bqls.searchTables
- workspace/didChangeConfiguration
- bqls/virtualTextDocument
- bqls/publishVirtualTextDocument
