Skip to main content

Limitations

VirtualMetric's KQL compiler parses the full Kusto Query Language grammar and translates the large majority of standard analytical KQL into executable SQL. A small set of constructs, however, has no faithful single-query SQL equivalent. This page lists what is not translated, explains why, and describes exactly what the compiler does when it encounters one — so there are no surprises when you bring an existing query across.

Every query is parsed successfully; the limitations below apply to the translation step, not parsing.

Unsupported Constructs​

For most of these the compiler emits an UNSUPPORTED marker rather than silently producing incorrect SQL. Treat the presence of an UNSUPPORTED marker as "not convertible for this target" — the surrounding query still compiles, but this construct does not.

The facet / find / reduce / macro-expand / make-graph row is the exception, and it behaves differently in a way that matters. Read the warning under the table before relying on any of those five.

ConstructWhy it is not translatedBehavior
search "term"Expanding a bare search term to per-column matches requires the table's column list (schema), which the text-only compiler does not haveUNSUPPORTED
evaluate pivot(...)The output columns depend on the distinct data values, which are unknowable at translation timeUNSUPPORTED
scanA stateful, row-sequential state machine with no general set-based SQL equivalentUNSUPPORTED
autocluster, basket, diffpatterns, narrowMachine-learning and heuristic algorithms with no SQL equivalentUNSUPPORTED
fork, invokePipeline-branching and macro constructs with no single-query SQL formUNSUPPORTED
facet, find, reduce, macro-expand, make-graphNot present in the grammar at all — see the warning belowParse error, partial result
Management / dot commands (.create, .set, .append, .ingest, …)Data-definition and ingestion commands, outside the scope of federated read queriesUNSUPPORTED
externaldataDeclares an external file source with no SQL equivalentUNSUPPORTED
warning

The UNSUPPORTED marker only appears for a construct the grammar can PARSE. facet, find, reduce, macro-expand and make-graph have no grammar rule, so they never reach the stage that would emit the marker.

The Kusto grammar error-recovers instead of failing, so a query containing one of them yields a partial parse tree and the compiler converts whatever it did understand. The parse errors are collected as warnings, but Kusto2SQL — the entry point used by the lookup query path — discards them (main.go:475-478). The result is a query that runs, returns rows, and reports success while having silently dropped part of what you asked for.

A query using one of these five returns wrong results rather than an error. Rewrite it without them; do not rely on a marker or a failure to tell you.

Because the compiler translates KQL text without an attached table schema, a few constructs are handled heuristically rather than exactly:

  • project-rename over an implicit SELECT * cannot rewrite a column name without knowing the full column list.
  • Typing of dynamic (JSON) column values is inferred heuristically rather than resolved from a declared type.

These are the cases addressed by the planned schema-aware mode described under Planned Improvements.

Execution vs. Semantic Equivalence​

Coverage is measured by generating SQL for each construct and running it against the target engine: a construct "passes" when the engine accepts and executes the SQL without error. This validates that the generated SQL is syntactically and structurally correct for the dialect — it does not assert row-for-row result equality with the originating platform.

A few conversions are deliberate approximations and are documented as such where they appear in the reference tables — for example make-series gap-filling and the tie-breaking behavior of arg_max. Where a construct is approximated for a given dialect, its cell in the reference tables is marked ⚠️ with a note.

Planned Improvements​

A schema-aware conversion mode is planned. VirtualMetric already ships normalized schemas (ASIM, OCSF, and Google UDM). Wiring an optional schema catalog into the compiler will turn several of the limitations above into supported features for normalized tables:

  • search will expand to the schema's real columns.
  • Dynamic and timespan typing will be resolved exactly instead of heuristically.
  • pivot and join column resolution will work over known tables.

This capability is on the roadmap and is not available yet.