fabric-eventhouse

Fabric Eventhouse / KQL Database

KQL management and query patterns specific to Fabric Eventhouse. Assumes familiarity with KQL — focus is on Fabric-specific behavior and az-rest-driven workflows.

Connection

• Cluster URI: each KQL Database has its own queryServiceUri, https://<cluster>.kusto.fabric.microsoft.com. Discover with GET /v1/workspaces/{wsId}/kqlDatabases (returns queryServiceUri + databaseName per item).
• Token audience: https://kusto.kusto.windows.net/.default for all direct access. A wrong audience surfaces as a 401 "Request is invalid and cannot be processed", not an auth error.
• Query endpoint: POST {clusterUri}/v1/rest/query, body {"db":"<dbName>", "csl":"<KQL>"}.
• KQL | breaks shell escaping — write the JSON body to a temp file and pass --body @<file>, never inline.

Worked az rest invocation and the REST item-definition envelope: references/programmatic-access.md.

Schema Discovery

.show tables
.show table T schema as json        // column names + types
.show table T details               // row count, extent count, size
.show functions
.show materialized-views
.show database principals           // who has what role

Schema Evolution

• .create-merge table is the safe / idempotent form — adds missing columns, never drops existing. Prefer over .create table for repeatable deployments.
• .alter-merge table T (NewCol: string) — add column.
• .rename column T.OldName to NewName — rename.
• .drop column T.OldCol — irreversible; fails if column is used in materialized view or function (drop dependents first).
• .drop table T ifexists — guarded drop.
• Atomic blue-green swap via .rename tables A=B, B=C, C=A (single command, atomic).

With OneLake availability ON the surface narrows: adding and deleting columns work (April 2026+), but altering a column type, renaming a table, applying RLS, and deleting/truncating/purging data do not — toggle availability off, change, toggle back on. Full matrix: references/onelake-availability.md.