fabric-realtime-dashboard

Fabric Real-Time Dashboard (KQLDashboard)

Hand-authoring and Git-editing the RealTimeDashboard.json definition. The portal load endpoint validates beyond JSON Schema conformance — most of what breaks a hand-authored dashboard is in the wiring rules below, not the syntax. Facts verified against a live dashboard (schema_version 81, Aug 2026) and Real-time dashboard - Git integration.

File anatomy

Item folder: <Name>.KQLDashboard/ with .platform + RealTimeDashboard.json (portal may name it RealTimeDashboard-N.json). Top-level keys: schema_version, flavor ("RTDashboard_Regular"), autoRefresh, tiles, baseQueries, parameters, dataSources, pages, queries, embeddedApps (+ portal-managed $schema/id/eTag/title, which a Git-created shell may omit — leave them however the portal wrote them).

All KQL text lives in queries[]; everything else points at it:

• queries[] — {id, dataSource: {kind: "inline", dataSourceId}, text, usedVariables}
• tiles[] — {id, queryRef: {kind: "query", queryId} | {kind: "baseQuery", baseQueryId}, title, visualType, pageId, layout, visualOptions}
• baseQueries[] — {id, variableName, queryId}; the text is the referenced query object. Variable names must start with _. A tile query that uses one references the variable in its KQL text and lists it in usedVariables. Base queries must each be a single tabular expression (they are wrapped as let _name = (<text>);) — no scalar lambdas, no internal let statements.
• parameters[] — kind: "duration" exposes two variables via beginVariableName / endVariableName (commonly _startTime / _endTime).
• dataSources[] — kind: "kusto-trident" with databaseArtifactId (the KQLDatabase item id) for Fabric-native sources.

Load-time validation rules

• Every queryId referenced exactly once, counted across tiles[].queryRef.queryId, baseQueries[].queryId, and parameters[].dataSource.queryRef.queryId. Duplicating a tile means duplicating its query with a fresh id too.
• Every id is an RFC-4122 UUID, unique within its category. Readable pseudo-ids are rejected. For deterministic scripted edits use uuid.uuid5(namespace, label).
• Misleading error: /tiles/N/queryRef ... must have required property 'baseQueryId' almost always means a malformed queryRef.queryId — the schema's oneOf fails the query branch and reports the baseQuery branch's complaints instead. Fix the UUID and the cascade clears.
• Identity preservation: never change existing ids (top-level, tile, page, query, dataSource, parameter), pageId, queryRef.queryId, dataSource.dataSourceId, parameter variableNames, or .platform logicalId. A changed identifier is treated as delete + recreate on the next Update from Git, losing pinned references and share targets.