KQL (Kusto Query Language)

KQL is the pipeline language of the SQL console and of the KQL tab in Explore. You start from a table and add steps with |. This page tells you which parts are verified, which are not, and how errors behave, so you do not have to guess. For plain SQL see the SQL console.

Open KQL#

Open SQL in the app and click KQL above the editor, or open Explore and switch a tab to KQL. You need the member role or higher. From an AI agent, use the MCP tool run_sql with "dialect": "kql" and an API key that has the sql scope.

logs
| where SeverityNumber >= 17
| summarize errors = count() by ServiceName
| order by errors desc

How a KQL query runs#

• Tables: logs, spans, trace_ids, metrics_gauge, metrics_sum, metrics_histogram, metrics_exponential_histogram and metrics_summary. A leading obs. is accepted.
• Time range: the range in the picker is applied for you, right after the first table, on that table's time column (Timestamp for logs and spans, Start for trace_ids, TimeUnix for metrics). The result reports whether the range was applied. A query that does not start from a table runs without a range.
• Narrow further with a filter on the time column inside the query.
• Rows: the console adds | take 10001 and shows up to 10,000 rows, and says so when it cut the result.
• Charts: keep the binned column's name, as in summarize count() by bin(Timestamp, 5m), and Chart draws it over time. A binned time column comes back as a time.
• Saving and export: Save and Recent remember the language. Export of KQL results is NDJSON only (Parquet is for SQL). Dashboard panels use SQL.
• Read-only, one query, the same limits and roles as the SQL console. Internal columns and keys are never returned: a query that names one is rejected with "is an internal column and cannot be queried" or "The query names an internal field".

What is verified#

The built-in KQL samples on the SQL page use these constructs, and Logthread's tests cover how the console adds the time range, caps the rows and hides internal columns around them:

They are used with where (== and >= comparisons), count(), sum() and avg().

Examples#

Every example here is one of the built-in samples on the SQL page: open KQL, then Start from an example.

Logs: the newest events

logs
| project Timestamp, SeverityText, ServiceName, Body
| order by Timestamp desc
| take 100

Logs: events over time (chartable)

logs
| summarize events = count() by bin(Timestamp, 5m)
| order by Timestamp asc

Logs: search the message

logs
| where Body contains "timeout"
| project Timestamp, ServiceName, Body
| take 100

Spans: slowest operations. Duration is nanoseconds, so / 1e6 gives milliseconds.

spans
| summarize p95_ms = percentile(Duration, 95) / 1e6, calls = count() by SpanName
| top 20 by p95_ms desc

Spans: failing services

spans
| where StatusCode == "Error"
| summarize errors = count() by ServiceName
| order by errors desc

Metrics: the busiest counters

metrics_sum
| summarize total = sum(Value) by MetricName
| top 20 by total desc

Metrics: gauge averages

metrics_gauge
| summarize avg_value = avg(Value) by MetricName
| take 50

Reference#

The tables below refresh automatically from the query engine: when you open this page they are replaced with the engine's current reference, and a line above them says when it was verified. Times are UTC. Large integers such as Duration and Count are 64-bit. metrics_exponential_histogram and metrics_summary are stored and queryable here; the Metrics page and alerts do not chart them. The schema browser on the SQL page lists the live columns.

Not verified yet#

These worked in earlier descriptions of KQL, but Logthread has no test for them: the translator runs in storage, so the behaviour is the storage engine's, not ours. Try one on your data before you rely on it, and fall back to SQL if it is rejected.

If the engine rejects a query, the console shows its message under the editor (code query_invalid). A query that reads too much data, runs too long or runs while the workspace is busy gets the same advice as SQL: narrow the range, filter earlier, retry shortly.

Next: the SQL console cookbook, or Analyze for pivots without a query.