/eventhouse-cli

name: eventhouse-cli
description: "Authors and queries Fabric Eventhouse and KQL databases: tables, functions, policies, materialized views, ingestion, and read-only KQL for real-time and time-series analytics. All KQL database work belongs here, table creation and simple queries included. An Eventstream item is eventstream-cli; an Event Schema Set is eventschemaset-cli."

> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry > `x-ms-fabric-skill: eventhouse-cli` (`az rest`: `--headers "x-ms-fabric-skill=eventhouse-cli"`), > including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway.

> **CRITICAL NOTES** > 1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering > 2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering > 3. **Skill disambiguation**: use `eventhouse-cli` for anything expressed in KQL or stored in a KQL Database. Use the matching `eventstream-cli` mode for streaming topology, and the matching `sqldw-*` skill for T-SQL against a Warehouse or Lakehouse SQL endpoint.

Fabric Eventhouse / KQL Database -- CLI Skill

This one skill owns Fabric Eventhouse and KQL Database: schema and ingestion management plus read-only KQL analytics.

It is a **mode dispatcher** and contains NO procedures. Pick the mode that matches the request from the table below, then **read the matching `references/<mode>.md` file end to end with your file-reading tool BEFORE issuing a single command**. That file holds the endpoints, payload shapes, templates and gotchas; acting without it produces wrong payloads and wrong results.

Mode selection

| Mode | Use when the request ... | Example triggers | Read this first | |---|---|---|---| | `authoring` | runs KQL management commands (`.create`, `.alter`, `.ingest`, `.drop`), policies, mappings, functions or materialized views | create kql table, kql ingestion, kql retention policy, kql function, materialized view, kql mapping | [references/authoring.md](references/authoring.md) | | `consumption` | runs read-only KQL (`where`, `summarize`, `join`, `render`), discovers schema with `.show`, or monitors ingestion health | kql query, query eventhouse, time-series kql, show tables kql, explore eventhouse | [references/consumption.md](references/consumption.md) |

Mode boundary rule

`consumption` may only issue read-only KQL and `.show` commands. Any dot-command that changes state (`.create`, `.alter`, `.ingest`, `.drop`, `.set-or-append`) requires the authoring mode: say so, read `references/authoring.md`, then proceed.

If a request genuinely spans modes, handle them one at a time and read each reference before you start that part. If the mode is ambiguous after reading this table, ask one short clarifying question instead of guessing.

Reference index

Read the mode reference first; open a topic file below only when the task needs it. Every reference is listed here, so read it from this table rather than following a link out of another reference.

| Reference | Read it when | |---|---| | [references/authoring.md](references/authoring.md) | any `authoring` request -- start here | | [references/authoring-core.md](references/authoring-core.md) | you need the capability matrix, table/schema, ingestion, policy, external table or permission detail behind an authoring task | | [references/authoring-advanced-operations.md](references/authoring-advanced-operations.md) | materialized views, stored functions, update policies, schema evolution, or monitoring authoring operations | | [references/authoring-scripts.md](references/authoring-scripts.md) | you want a ready-to-run script for create-and-ingest, schema deployment, export or policies -- **run them from `scripts/`, do not read them** | | [references/consumption.md](references/consumption.md) | any `consumption` request -- start here | | [references/consumption-discovery-queries.md](references/consumption-discovery-queries.md) | you need the `.show` discovery queries for schema, tables or ingestion health | | [EVENTHOUSE-CONSUMPTION-CORE.md](../../common/EVENTHOUSE-CONSUMPTION-CORE.md) | connection fundamentals, schema discovery and security, monitoring, performance best practices, or common KQL query patterns -- **read before writing KQL** |

Terminal write -- the step you must not skip

Reading the reference and planning the change is NOT completing the task. Each mutating mode ends with one state-changing call. If you did not issue it, nothing was persisted -- say so explicitly rather than reporting success.

| Mode | Terminal write | |---|---| | `authoring` | `POST .../v1/rest/mgmt` carrying the literal `.create-merge table` (or `CREATE TABLE`-equivalent), `.alter` or `.ingest` command. Composing the KQL management command and showing it to the user is not executing it. | | `consumption` | none -- this mode is read-only |

Before you report the task done, confirm the terminal call returned success and, where the reference documents a readback, read the artefact back to prove the change landed.

Shared essentials (all modes)

Resolve the workspace and item first; every mode depends on it.

| Task | Reference | Notes | |---|---|---| | Finding Workspaces and Items in Fabric | [COMMON-CLI.md](../../common/COMMON-CLI.md#finding-workspaces-and-items-in-fabric) | **Mandatory** -- read before resolving any workspace or item id | | Fabric Topology & Key Concepts | [COMMON-CORE.md](../../common/COMMON-CORE.md#fabric-topology--key-concepts) | Item types, workspaces, capacities | | Environment URLs | [COMMON-CORE.md](../../common/COMMON-CORE.md#environment-urls) | Sovereign / non-public cloud hosts | | Authentication & Token Acquisition | [COMMON-CORE.md](../../common/COMMON-CORE.md#authentication--token-acquisition) | Wrong audience = 401; read before any auth issue | |