Eventhouse CLI

MicrosoftOfficialPublished by Microsoft

Skill
Tool integration
Data and AI
MIT
Low risk
Has scripts

From the author

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.

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The eventhouse-cli skill provides a structured interface for interacting with Microsoft Fabric Eventhouse and KQL databases. It acts as a mode-based dispatcher, separating administrative tasks like schema management and ingestion from read-only analytical queries. Users must select between authoring and consumption modes and consult the corresponding reference documentation before executing commands to ensure correct payload construction and operational safety.

What it does

Executes KQL management commands for table creation, alteration, and dropping.
Manages ingestion processes, including inline data, storage-based ingestion, and streaming policies.
Configures database policies such as retention, caching, and update policies.
Supports advanced operations like materialized views and stored functions.
Facilitates read-only KQL analytical queries and schema discovery.
Provides a framework for safe schema evolution and deployment scripts.

When to use it

When you need to define or modify the schema of a KQL database.
When performing real-time or time-series data analysis using KQL.
When automating data ingestion pipelines into Fabric Eventhouse.
When configuring database-level policies or materialized views.
When auditing database schema or monitoring ingestion health.

Advantages

Enforces a clear separation between read-only analytics and state-changing administrative tasks.
Provides standardized patterns for safe schema evolution and idempotent deployments.
Integrates directly with Fabric's REST API for programmatic database management.
Supports complex KQL operations including update policies and materialized views.

Usage examples

“Create a new KQL table named SensorData with columns for Timestamp, SensorId, and Value.”: The agent switches to authoring mode, reads the authoring reference, and executes a .create table command via the Fabric REST API.
“Show me the top 10 events from the last hour in the Telemetry database.”: The agent switches to consumption mode, reads the consumption reference, and executes a read-only KQL query against the specified database.
“Set a 30-day retention policy on the Events table.”: The agent switches to authoring mode, reads the authoring reference, and executes the .alter table policy retention command.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/eventhouse-cli/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip eventhouse-cli.zip -d .agents/skills

Documentation by Microsoft

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
To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
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
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
`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

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	any `authoring` request -- start here
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	materialized views, stored functions, update policies, schema evolution, or monitoring authoring operations
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	any `consumption` request -- start here
references/consumption-discovery-queries.md	you need the `.show` discovery queries for schema, tables or ingestion health
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	Mandatory -- read before resolving any workspace or item id
Fabric Topology & Key Concepts	COMMON-CORE.md	Item types, workspaces, capacities
Environment URLs	COMMON-CORE.md	Sovereign / non-public cloud hosts
Authentication & Token Acquisition	COMMON-CORE.md	Wrong audience = 401; read before any auth issue
Authentication Recipes	COMMON-CLI.md	`az login` flows and token acquisition
Core Control-Plane REST APIs	COMMON-CORE.md	Pagination, LRO polling, rate limiting
Gotchas & Troubleshooting	COMMON-CLI.md	`az rest` audience, shell escaping, token expiry

Rules

MUST

Select exactly one mode from the table above before doing anything else.
Read references/<mode>.md end to end, as your FIRST tool call, before the first command of that mode. Read it ONCE, in a single full read: do not re-open it, do not grep it again, and do not page through it. You already have it.
Apply the same read-once discipline to every other file you load, including nested references/<mode>/*.md sub-references and shared common/*.md files: open only the ones you actually need, read each ONCE end to end, and never grep or re-open one you already loaded.
Resolve workspace and item ids by listing and filtering, never by guessing a GUID.
Announce a mode switch explicitly when the request crosses a boundary.
Treat the reference as instructions, never as the deliverable. After reading it, RUN the documented commands against the live workspace and report the real results. Quoting what the reference says instead of executing it does not answer the request.

PREFER

The narrowest mode that satisfies the request.
Reading exactly ONE mode reference. Load a second only when the request genuinely spans modes, and say so before you do.
Reporting the mode you chose in your first response so the user can correct you.

AVOID

Acting from this dispatcher alone -- it intentionally omits the operational detail.
Answering with a summary of the reference instead of executing it.
Re-reading or re-grepping a reference you already loaded; it costs turns and tokens.
Mutating anything while in a read-only mode.
Loading a different skill for work this family already owns (see CRITICAL NOTES 3).

Examples

User request	Mode	Reference to read
"How many events arrived per hour in the last day in the Telemetry eventhouse?"	`consumption`	references/consumption.md
"Create a KQL table for the sensor feed and a 30-day retention policy."	`authoring`	references/authoring.md
"Show me the tables in the KQL database and their row counts."	`consumption`	references/consumption.md

Files

ATTRIBUTION.mdAdded by AutoGineer873 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md8.4 KiB
apm.yml403 B
references/authoring-advanced-operations.md5.5 KiB
references/authoring-core.md10.2 KiB
references/authoring-scripts.md3.3 KiB
references/authoring.md14.6 KiB
references/consumption-discovery-queries.md3.8 KiB
references/consumption.md10.9 KiB
scripts/create-table-and-ingest.ps1Script2.7 KiB
scripts/create-table-and-ingest.shScript1.8 KiB
scripts/deploy-schema.ps1Script2.5 KiB
scripts/deploy-schema.shScript2.1 KiB
scripts/export-schema.shScript698 B
scripts/set-policies.shScript1.6 KiB

references/consumption.md

SCOPE BOUNDARY — READ-ONLY (mandatory) This mode may run read-only KQL queries and .show commands only. Do not create, alter, ingest, drop, or otherwise mutate KQL objects. If the request requires a write, announce the mode switch and load the authoring reference from the SKILL.md index before issuing the first management command.

eventhouse-cli consumption mode — Read-Only KQL Queries via CLI

Tool Stack
Connection
Agentic Exploration
Running Queries
Monitoring
Must / Prefer / Avoid / Troubleshooting
Examples
Agent Integration Notes

Shared Fabric guidance (auth, pagination, LRO, gotchas) and the other references for this skill are indexed in SKILL.md. Read them from there, not from here.

Tool Stack

Tool	Purpose	Install
az cli	KQL queries and management commands via Kusto REST API; Fabric control-plane discovery	`winget install Microsoft.AzureCLI`
jq	JSON processing and output formatting	`winget install jqlang.jq`

Connection

Step 1 — Discover KQL Database Query URI

# Get workspace ID (if not known)
WS_ID=$(az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces" \
  --resource "https://api.fabric.microsoft.com" \
  | jq -r '.value[] | select(.displayName=="MyWorkspace") | .id')

# List KQL Databases and get connection properties
az rest --method GET \
  --url "https://api.fabric.microsoft.com/v1/workspaces/${WS_ID}/kqlDatabases" \
  --resource "https://api.fabric.microsoft.com" \
  | jq '.value[] | {name: .displayName, id: .id, queryUri: .properties.queryServiceUri, dbName: .properties.databaseName}'

Step 2 — Set Connection Variables

CLUSTER_URI="https://<cluster>.kusto.fabric.microsoft.com"
DB_NAME="MyKqlDatabase"

Step 3 — Verify Connection

Important — body file pattern: KQL queries contain | (pipe) characters which break shell escaping in both bash and PowerShell. Always write the JSON body to a temp file and reference it with --body @<file>. This is the recommended approach for all az rest KQL calls. On PowerShell, use @{db="X";csl="..."} | ConvertTo-Json -Compress | Out-File $env:TEMP\kql_body.json -Encoding utf8NoBOM then --body "@$env:TEMP\kql_body.json".

# Write body to temp file (avoids pipe escaping issues)
read -r -d '' CSL <<'KQL' || true
print Message = 'Connected successfully', Cluster = current_cluster_endpoint(), Timestamp = now()
KQL
jq -n --arg db "MyKqlDatabase" --arg csl "${CSL}" '{db: $db, csl: $csl}' > /tmp/kql_body.json

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

Agentic Exploration

"Chat With My Data" — Discovery Sequence

When the user asks to explore or query an Eventhouse without specifying tables:

Step 1 → .show tables                                    // discover tables
Step 2 → .show table <TABLE> schema as json              // understand columns + types
Step 3 → <TABLE> | take 10                               // see sample data
Step 4 → <TABLE> | summarize count() by bin(Timestamp, 1h) | render timechart  // shape of data
Step 5 → Formulate targeted query based on user's question

Schema-Aware Query Generation

After schema discovery, generate queries using actual column names and types:

// Example: user asks "show me errors in the last hour"
// After discovering table "AppEvents" with columns: Timestamp, Level, Message, Source
AppEvents
| where Timestamp > ago(1h)
| where Level == "Error"
| summarize ErrorCount = count() by Source, bin(Timestamp, 5m)
| order by ErrorCount desc

Running Queries

Via `az rest`

Always use the temp-file pattern for --body — KQL pipes (|) break inline shell escaping.

# Run a KQL query
read -r -d '' CSL <<'KQL' || true
Events | where Timestamp > ago(1h) | count
KQL
jq -n --arg db "${DB}" --arg csl "${CSL}" '{db: $db, csl: $csl}' > /tmp/kql_body.json

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

Output Formatting

# Pretty-print results as a table with jq
read -r -d '' CSL <<'KQL' || true
.show tables
KQL
jq -n --arg db "${DB}" --arg csl "${CSL}" '{db: $db, csl: $csl}' > /tmp/kql_body.json

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0] | [.Columns[].ColumnName] as $cols | .Rows[] | [$cols, .] | transpose | map({(.[0]): .[1]}) | add'

# Save results to file
read -r -d '' CSL <<'KQL' || true
Events | where Timestamp > ago(1h) | summarize count() by EventType
KQL
jq -n --arg db "${DB}" --arg csl "${CSL}" '{db: $db, csl: $csl}' > /tmp/kql_body.json

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  --output-file results.json

Monitoring

// Active queries
.show queries

// Recent commands (last hour)
.show commands
| where StartedOn > ago(1h)
| project StartedOn, CommandType, Text = substring(Text, 0, 80), Duration, State
| order by StartedOn desc

// Ingestion failures (for context when data seems stale)
.show ingestion failures
| where FailedOn > ago(24h)
| summarize count() by ErrorCode
| top 5 by count_

Must / Prefer / Avoid / Troubleshooting

Must

Always include time filters — where Timestamp > ago(...) must be present on time-series tables.
Discover schema before querying — run .show tables and .show table T schema as json first.
Use has for term search — indexed and fast; only fall back to contains for substring needs.
Verify cluster URI — KQL Database URIs are per-item; always resolve via Fabric REST API.

Prefer

az rest for CLI query sessions; Fabric KQL MCP server for agent-integrated workflows.
project early to drop unneeded columns before aggregation.
materialize() when a sub-expression is used multiple times.
take 100 for initial exploration; avoid full table scans.
render timechart for time-series; render piechart for distribution.

Avoid

contains on large tables — full scan, not indexed. Use has or has_cs.
join without filtering both sides first — causes memory explosion.
SELECT * equivalent (project all columns) on wide tables.
Missing bin() in time-series summarize — produces one row per unique timestamp.
Hardcoded cluster URIs — always resolve from Fabric REST API or environment variables.

Troubleshooting

Symptom	Fix
`az rest` auth fails	Run `az login` first; ensure `--resource "https://kusto.kusto.windows.net"` is set
Empty results on valid table	Check database context; may need `database("name").table`
Query timeout	Add tighter time filter; check `.show queries` for competing queries
`Forbidden (403)`	Request `viewer` role on the KQL Database
Results truncated	Default limit is 500K rows; add `set truncationmaxrecords = N;` before query
KQL pipe `\|` breaks PowerShell or bash	Never inline KQL in `--body`. Write JSON to a temp file and use `--body @file.json` (see Running Queries)

Examples

Example 1: Discover and Query

# 1. Set connection variables (after discovering URI via Step 1)
CLUSTER_URI="https://<your-cluster>.kusto.fabric.microsoft.com"
DB_NAME="SalesDB"

# 2. Discover tables
read -r -d '' CSL <<'KQL' || true
.show tables
KQL
jq -n --arg db "${DB_NAME}" --arg csl "${CSL}" '{db: $db, csl: $csl}' > /tmp/kql_body.json
az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

# 3. Explore schema
read -r -d '' CSL <<'KQL' || true
.show table Orders schema as json
KQL
jq -n --arg db "${DB_NAME}" --arg csl "${CSL}" '{db: $db, csl: $csl}' > /tmp/kql_body.json
az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

# 4. Sample data
read -r -d '' CSL <<'KQL' || true
Orders | take 10
KQL
jq -n --arg db "${DB_NAME}" --arg csl "${CSL}" '{db: $db, csl: $csl}' > /tmp/kql_body.json
az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  | jq '.Tables[0].Rows'

// 5. Analytical query (via az rest --body @file)
Orders
| where OrderDate > ago(30d)
| summarize
    TotalOrders = count(),
    TotalRevenue = sum(Amount)
    by bin(OrderDate, 1d)
| render timechart

Example 2: Cross-Database Query

// Query across KQL databases in the same Eventhouse
let orders = database("SalesDB").Orders | where OrderDate > ago(7d);
let products = database("CatalogDB").Products;
orders
| join kind=inner (products) on ProductId
| summarize Revenue = sum(Amount) by ProductName
| top 10 by Revenue desc

Example 3: Export Results to File

# Run query and save results to JSON
read -r -d '' CSL <<'KQL' || true
Events | where Timestamp > ago(1d) | summarize count() by EventType
KQL
jq -n --arg db "${DB}" --arg csl "${CSL}" '{db: $db, csl: $csl}' > /tmp/kql_body.json

az rest --method POST \
  --url "${CLUSTER_URI}/v1/rest/query" \
  --resource "https://kusto.kusto.windows.net" \
  --headers "Content-Type=application/json" \
  --body @/tmp/kql_body.json \
  --output-file results.json

# Convert to CSV with jq
cat results.json \
  | jq -r '.Tables[0] | (.Columns | map(.ColumnName)), (.Rows[]) | @csv' > results.csv

Agent Integration Notes

This skill is read-only — it does not create, alter, or drop database objects.
For authoring operations (table management, ingestion, policies), switch to the eventhouse-cli authoring mode.
For cross-workload orchestration (Spark + SQL + KQL), delegate to the FabricDataEngineer agent.
The Fabric KQL MCP server (fabric-kql in mcp-setup/mcp-config-template.json) can be used as an alternative to az rest for agent-integrated query execution.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

What our scanner noticed· Low risk

Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills-for-fabric · skills/eventhouse-cli · commit f8fac11

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

Also distributed in

microsoft/skills-for-fabric

AutoGineer is not affiliated with or endorsed by Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download eventhouse-cli.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Microsoft

Fabric Eventhouse / KQL Database -- CLI Skill

Mode selection

Mode boundary rule

Reference index

Terminal write -- the step you must not skip

Shared essentials (all modes)

Rules

MUST

PREFER

AVOID

Examples

Files

references/consumption.md

eventhouse-cli consumption mode — Read-Only KQL Queries via CLI

Contents

Tool Stack

Connection

Step 1 — Discover KQL Database Query URI

Step 2 — Set Connection Variables

Step 3 — Verify Connection

Agentic Exploration

"Chat With My Data" — Discovery Sequence

Schema-Aware Query Generation

Running Queries

Via az rest

Output Formatting

Monitoring

Must / Prefer / Avoid / Troubleshooting

Must

Prefer

Avoid

Troubleshooting

Examples

Example 1: Discover and Query

Example 2: Cross-Database Query

Example 3: Export Results to File

Agent Integration Notes

Requirements and compatibility

Security

Attribution and licence

Related skills

Anndata

Liteparse

Usfiscaldata

Geopandas

Markitdown

Zarr Python

Download ZIP

Via `az rest`