Skip to content

Add KQL as a text container language, highlighted and formatted - #103

Merged
marcosqlbi merged 1 commit into
mainfrom
feature/kql-language
Sep 6, 2026
Merged

Add KQL as a text container language, highlighted and formatted#103
marcosqlbi merged 1 commit into
mainfrom
feature/kql-language

Conversation

@marcosqlbi

Copy link
Copy Markdown
Collaborator

Closes #101.

Kusto Query Language joins DAX and SQL Server: a text container can be KQL, the
title-bar chip offers it, F6 formats it, and .kql files and kql / kusto
fences import as KQL.

Why this shape

SQLBI.Whiteboard.Kql wraps Microsoft.Azure.Kusto.Language the way
SQLBI.Whiteboard.SqlServer wraps ScriptDOM. Microsoft ships the parser, the
classifier, and the formatter for their own language, so unlike DAX there is no
grammar to write here and nothing to keep current by hand as KQL grows. The
package is Apache-2.0, has no dependencies of its own, and targets
netstandard2.0.

Only the syntax is judged. A board carries a snippet rather than a connection,
so the semantic pass reports every table and column it cannot resolve; all of
those would be false alarms on a whiteboard, so acceptance and the F6 guard both
read syntax diagnostics alone.

The one place the library default was overridden

Formatting keeps the author's spacing around the assignment sign. The library
default writes join kind = inner hint.strategy = broadcast, which rewrites the
hints that real queries carry; the examples on the issue are all written the
tight way. Everything else is the library's own layout.

As with DAX and SQL, formatting compares the tokens and the comments before and
after and returns the text untouched when they differ, so F6 can never quietly
change a query.

Notes for review

  • The language is appended last everywhere, so a board or a settings file saved
    before this release keeps its Snippet format order and simply gains KQL at the
    end. There is a test for that.
  • A bare word is a valid KQL query, so KQL would claim Agenda if it were tried
    before Plain text. Plain text stays first by default and always accepts, so
    this only reaches someone who has reordered the list deliberately.
  • SQLBI.Whiteboard.Kql.dll is in the pipeline signing list. The installer
    harvests the publish folder, so it and Kusto.Language.dll need nothing there.
  • Verified in the running application, not only in tests: both containers of a
    .wimport imported as KQL, highlighted, and F6 reformatted a one-line query
    in place while keeping T=7d and kind=inner as written.

dotnet build Whiteboard.sln -c Release is clean with no warnings, and the
smoke tests pass.

🤖 Generated with Claude Code

Kusto Query Language joins DAX and SQL Server in the language chip, in
F6, in the .wimport contract, and in Snippet format order.

SQLBI.Whiteboard.Kql wraps Microsoft.Azure.Kusto.Language the way
SQLBI.Whiteboard.SqlServer wraps ScriptDOM: Microsoft ships the parser,
the classifier, and the formatter, so there is no grammar to write and
nothing to keep current by hand.

Only the syntax is judged. A board carries a snippet rather than a
connection, so the semantic pass reports every table it cannot resolve
and all of those would be false alarms.

Formatting keeps the author's spacing around the assignment sign, so
that a join written as kind=inner survives it. The library default puts
spaces there, which rewrites the hints most queries carry.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@marcosqlbi
marcosqlbi merged commit 544350c into main Sep 6, 2026
5 checks passed
@marcosqlbi
marcosqlbi deleted the feature/kql-language branch September 6, 2026 03:41
marcosqlbi added a commit that referenced this pull request Sep 6, 2026
…earn a snippet (#105)

## Why

Snippet format order decides which language a paste becomes: the first
that accepts the text wins, and plain text accepts everything. With
plain text first, the shipped default since 1.0, every paste was a note
until someone found the setting, and a language added by an update (KQL
in #103) joined the end of the list, behind plain text, and never
applied. The goal is that a new language works on the day it ships, with
no visit to Preferences. Decision 28 records the reasoning, including
why the checkbox that was considered was not added.

## What changes

- **The default order is DAX, SQL, KQL, Plain text.**
- **Upgrades.** A saved order equal to a default the application ever
shipped (plain text first, with or without KQL) was never chosen by
anyone and takes the new default once, keyed on the settings version
moving to 16. A chosen order is kept, and a language it does not know
joins it in front of plain text wherever plain text sits; only an order
that starts with plain text, which means "keep my pastes plain", gets
new languages last.
- **A language must earn a snippet.** Every parser accepts a bare name
or a number: `Sales` is a DAX table expression and a KQL query, so with
plain text last a one-word note would have become code. Each engine
gains `LooksLike`: DAX needs a function, operator, keyword, column
reference, or variable; T-SQL a keyword or function; KQL a pipe, query
operator, keyword, command, or function. The parser still decides after
the signal.
- Preferences text, README, the guide, and the 1.3.0 release notes say
how it works now.

## Tests

Smoke tests cover the new default, insertion in front of plain text, the
plain-first exception, the version-15 migration of both shipped
defaults, a customized version-15 order kept, a version-16 plain-first
order left alone, and the three gates with bare words, numbers, prose,
and real snippets.

Not to be merged yet.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support KQL (syntax highlight and format)

1 participant