KeyQL Syntax Highlighting

A Visual Studio Code extension that provides syntax highlighting for Microsoft's Keyword Query Language (KeyQL / KQL) — the query language used across SharePoint Search, Microsoft Search, and Microsoft Purview eDiscovery.

The color scheme intentionally mirrors SQL: boolean operators are highlighted like SQL keywords, property names like column identifiers, quoted phrases like strings, and numbers/dates like numeric constants — so it should look familiar in any theme you already use for SQL.

Download

Download the latest .vsix →

Then install it with:

code --install-extension keql-syntax-0.1.0.vsix

Or in VS Code: Extensions view ▸ ... menu ▸ Install from VSIX…. Every version is also attached to the Releases page.

Features

Highlighting for the full KeyQL surface:

Element	Example	Scope
Logical operators	AND, OR, NOT	keyword.operator.logical
Proximity / ranking	NEAR, ONEAR, XRANK, WORDS	keyword.operator.word
Property names	author:, filetype:, size	entity.other.attribute-name
Comparison operators	: = <> < > <= >=	keyword.operator.comparison
Quoted phrases	"exact phrase"	string.quoted.double
Numbers	1024, 3.14	constant.numeric
Dates	2026-01-01, ISO timestamps	constant.numeric.date
Booleans	true, false	constant.language.boolean
Wildcards	report*	keyword.operator.wildcard
Grouping	( ... )	meta.group
Comments	// ...	comment.line

Recognized file extensions: .keql, .kql.

Formatting

The extension also contributes a document formatter, available through Format Document (Shift+Alt+F / Cmd+Shift+P → Format Document) or via format-on-save. It reflows KeyQL into a consistent, SQL-style layout:

• Uppercases boolean/proximity operators (and → AND, near → NEAR).
• Removes whitespace around property operators (author : "x" → author:"x").
• Uses a single space between free-text terms and collapses extra whitespace.
• Breaks grouped ( … ) and top-level AND/OR chains onto their own indented lines (indent follows your editor's tab settings).
• Preserves blank lines and full-line // comments between queries, treating each blank-line-separated block as its own query.

For example:

(author:"Jane" OR author:"John") AND NOT filetype:pdf

formats to:

(
    author:"Jane"
    OR author:"John"
)
AND NOT filetype:pdf

To format on save, add to your settings:

"[keql]": { "editor.formatOnSave": true }

Note: KeyQL boolean operators must be UPPERCASE (AND, not and) to be treated as operators by Microsoft's search engine. The grammar matches only the uppercase forms, so a lowercase and is (correctly) treated as free text.

Manual installation (for testing)

There are two easy ways to load the extension locally without publishing it to the Marketplace.

Option A — Run from source (Extension Development Host)

This is the fastest way to iterate on the grammar.

1. Clone and open this folder in VS Code:

   git clone https://github.com/saltypoison/keql-syntax.git
   code keql-syntax

2. Press F5 (or Run ▸ Start Debugging). VS Code launches a second window titled [Extension Development Host] with the extension loaded.
3. In that new window, open examples/sample.keql (or create any .keql file). You should see syntax highlighting immediately.
4. Edit syntaxes/keql.tmLanguage.json, then in the dev-host window run Developer: Reload Window (Cmd+R) to see changes.

Option B — Install into your normal VS Code (symlink or copy)

This makes the extension available in your everyday editor for all .keql files.

1. Copy (or symlink) this folder into your VS Code extensions directory:

   macOS / Linux:

   ln -s "$(pwd)" ~/.vscode/extensions/keql-syntax-0.1.0

   (Use cp -R instead of ln -s if you'd rather copy than symlink.)

   Windows (PowerShell):

   Copy-Item -Recurse "C:\path\to\KeyQLPlugin" "$env:USERPROFILE\.vscode\extensions\keql-syntax-0.1.0"

2. Fully quit and reopen VS Code.

3. Open any .keql or .kql file — highlighting is applied automatically.

Option C — Package as a .vsix and install

If you want a single installable file (e.g. to share with a teammate):

1. Install the packaging tool once:

   npm install -g @vscode/vsce

2. From this folder, build the package:

   vsce package

   This produces keql-syntax-0.1.0.vsix.
3. Install it:

   code --install-extension keql-syntax-0.1.0.vsix

   Or in VS Code: Extensions view ▸ ... menu ▸ Install from VSIX….

Verifying it works

Open examples/sample.keql and confirm that:

• AND / OR / NOT are colored like keywords,
• property names before : / = / > are colored like identifiers,
• "quoted phrases" are colored like strings,
• numbers and 2026-01-01 dates are colored like constants.

To inspect the exact scope applied to any token, run Developer: Inspect Editor Tokens and Scopes from the Command Palette and click on a token.

Project structure

KeyQLPlugin/
├── package.json                  # Extension manifest (language + grammar + formatter)
├── language-configuration.json   # Brackets, auto-closing pairs, comments
├── extension.js                  # Entry point: registers the formatter with VS Code
├── formatter.js                  # Formatting logic (dependency-free, unit-testable)
├── syntaxes/
│   └── keql.tmLanguage.json       # The TextMate grammar (all highlighting rules)
├── examples/
│   └── sample.keql                # Example queries for testing
├── docs/
│   ├── index.html                 # Download page (published via GitHub Pages)
│   └── keql-syntax-0.1.0.vsix     # Packaged extension served by that page
├── .vscode/
│   └── launch.json                # F5 "Run Extension" configuration
└── README.md

The formatter is written in plain JavaScript with no dependencies and no build step — VS Code's extension host runs extension.js directly. There's nothing to npm install before pressing F5.

License

MIT