Kustology

Not affiliated with Microsoft. This is an independent open-source project that wraps Microsoft's publicly distributed Apache 2.0–licensed library.

Kustology gives Python programs Microsoft's own KQL parser, the one behind Azure Data Explorer, Azure Monitor, and Microsoft Sentinel. It loads the official Kusto.Language library through pythonnet, so queries parse exactly as the service parses them.

The library comes in two tiers. Either one works on its own.

The two tiers

Tier 1: thin wrapper

Tier 1 exposes Microsoft's parser, formatter, and validator, and adds analyzers for the questions a KQL author asks most: which tables a query reads, which columns it touches, which operators it chains, where its time filters sit, and how to rename a table everywhere it appears. You work with Microsoft's syntax tree directly.

Tier 2: semantic IR

Tier 2 builds a typed Pydantic model of the parsed query, with classes like FilterOp, BinOp, and ColumnRef. It suits the questions an analyzer asks: which source table a column came from after joins, renames, and let aliases; what schema the pipeline produces; whether two queries mean the same thing despite formatting; how much two queries overlap or where two versions of a rule diverge; and how to serialize the whole graph for a UI, a service, or a language model.

Choosing a tier

Both tiers use the same parser. Pick based on the shape of data your code wants.

Prerequisites

• Python 3.10 or later
• .NET 8.0+ runtime

If you installed dotnet through Homebrew, its runtime layout differs from Microsoft's installer and libhostfxr.dylib sits under libexec/ instead of bin/. Kustology detects this. If detection fails, set DOTNET_ROOT yourself:

export DOTNET_ROOT=/opt/homebrew/opt/dotnet/libexec   # Apple Silicon
export DOTNET_ROOT=/usr/local/opt/dotnet/libexec      # Intel

Installation

pip install kustology             # Tier 1: thin .NET wrapper
pip install 'kustology[ir]'       # Tier 1 + Tier 2: semantic IR (adds pydantic)
pip install 'kustology[examples]' # Colour output in examples/ (adds rich)

Quick start

from kustology import parse, format_query

query = (
    "StormEvents | where StartTime > ago(7d) and DeathsDirect > 0 "
    "| project StartTime, State, EventType"
)

print(format_query(query))

result = parse(query)
result.get_referenced_tables()      # {'StormEvents'}
result.get_referenced_columns()     # {'StartTime', 'DeathsDirect', 'State', 'EventType'}
result.get_referenced_functions()   # {'ago'}

# Pass a schema to bind the query and get semantic diagnostics.
schema = {"StormEvents": {"StartTime": "datetime", "DeathsDirect": "int",
                          "State": "string", "EventType": "string"}}
bound = parse(query, schema=schema)
bound.has_semantics                 # True
bound.diagnostics                   # []

With the [ir] extra installed, the same parse builds a Pydantic IR:

from kustology import parse
from kustology.ir import FilterOp

schema = {"StormEvents": {"DeathsDirect": "int", "State": "string"}}
ir = parse("StormEvents | where DeathsDirect > 0", schema=schema).to_ir()

for op in ir.main_pipeline.operators:
    if isinstance(op, FilterOp):
        op.predicate.canonical_form   # StormEvents.DeathsDirect > 0
        op.predicate.left.table       # StormEvents
        op.predicate.left.result_type # int  (KustoType.INT)

CLI

The kustology console script ships with the base install:

kustology format query.kql        # reformat to canonical form
kustology validate query.kql      # print parser diagnostics
kustology parse --ir query.kql    # print the Pydantic IR (needs [ir])
kustology sources query.kql       # report every source the query reads

Every subcommand, the --schema and --json flags, and the exit codes CI branches on are in the CLI reference.

Examples

Each script runs standalone and explains its own output as it goes, and tests/test_examples.py runs all of them, so none can drift away from the library without CI noticing.

The IR examples need the [ir] extra. The rest run on the base install. Add the [examples] extra for colour and syntax highlighting; without it the same output prints as plain text.

Documentation

Versioning

This is a 0.y release, so the public API can still change at a minor version (SemVer §4). Tier 1 is on a stabilization track and reaches 1.0 once it survives external use without correctness breaks. Tier 2 keeps evolving at minor cadence.

Three numbers describe compatibility: kustology.__version__ tags the library, kustology.ir.IR_SCHEMA_VERSION tags the IR's field shape, and kustology.ir.SEMANTIC_HASH_SCHEME tags the hash canonicalization rules. A QueryIR dump carries its ir_schema_version, and QueryIR.model_validate rejects a dump tagged with any other version or with none. A semantic_hash carries its scheme as a prefix. See Versioning and semantic_hash for the full contract.

Development

git clone https://github.com/k4otix/kustology.git
cd kustology
uv sync --locked --extra dev

uv run pytest
uv run ruff check src tests scripts examples
uv run mypy src

See CONTRIBUTING.md for the full workflow.

License

Apache License 2.0. See LICENSE, NOTICE.md, and THIRD-PARTY-NOTICES.md. The bundled Kusto.Language.dll is owned by Microsoft Corporation and redistributed unmodified under Apache 2.0. It is pinned by SHA-256 and verified in CI. See SECURITY.md.

Trademark notice

"Kusto", "KQL", "Microsoft", "Azure Data Explorer", "Azure Monitor", and "Microsoft Sentinel" are trademarks of Microsoft Corporation. References to those trademarks are nominative and used only to identify the upstream library this package wraps. Apache License 2.0 §6 does not grant trademark rights; nothing in this distribution should be construed as a trademark license.