/sqldw-cli

name: sqldw-cli
description: "Manage Fabric Warehouse, Lakehouse SQL endpoints, and Mirrored Databases: DDL/DML, COPY INTO, read-only T-SQL, Query Insights diagnostics, and Capacity Metrics CU-spike correlation. Synapse migration target SQL belongs to synapse-migration; Fabric SQL database belongs to sqldb-cli. Triggers: query warehouse, create warehouse table, failed or canceled query, CU spike, Capacity Metrics app, custom SQL pool, Lakehouse table health."

> **Telemetry — MANDATORY.** Every `api.fabric.microsoft.com` call must carry > `x-ms-fabric-skill: sqldw-cli` (`az rest`: `--headers "x-ms-fabric-skill=sqldw-cli"`), > including every LRO poll, `fabric_lro` and retry. Snippets omit it — add it anyway. > This covers all three modes; the mode references inherit it.

> **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 `sqldw-cli` for T-SQL sent to a Warehouse, a Lakehouse SQL analytics endpoint, or a Mirrored Database, including plain Lakehouse table SELECT, row-count, filtering, and aggregation requests. Target Warehouse SQL executed within an end-to-end Azure Synapse or Dedicated SQL Pool migration belongs to `synapse-migration`; standalone Warehouse work before or after migration returns to `sqldw-cli`. Any notebook-cell or PySpark DataFrame work is `spark-cli`; a Fabric SQL database (OLTP) is `sqldb-cli`.

Fabric Warehouse and SQL Endpoints — CLI Skill

This one skill owns Fabric Warehouse, Lakehouse SQL analytics endpoints and Mirrored Databases: T-SQL authoring and ingestion, read-only querying, and warehouse performance diagnostics.

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 T-SQL surface area, DDL constraints, query templates and gotchas; acting without it produces invalid T-SQL and wrong results.

Mode selection

| Mode | Use when the request ... | Example triggers | Read this first | |---|---|---|---| | `authoring` | changes warehouse state: table DDL, DML, ingestion, transactions, procedures, schema evolution, time travel | create warehouse table, COPY INTO, OPENROWSET, INSERT/UPDATE/DELETE, warehouse MERGE, CTAS, sp_rename, create T-SQL procedure, warehouse time travel | [references/authoring.md](references/authoring.md) | | `consumption` | reads data or metadata: SELECT, row counts, filtering, aggregation, schema/object discovery, CSV export | query warehouse, count rows lakehouse, SELECT lakehouse, show tables, describe warehouse schema, export SQL data | [references/consumption.md](references/consumption.md) | | `operations` | diagnoses performance, failures, capacity consumption, SQL pool usage, or health through `queryinsights` and supported endpoint diagnostics | failed or canceled warehouse queries, CU spike, Capacity Metrics app, expensive SQL users, custom SQL pool recommendation, queryinsights CPU, pressure events, cache warmth, Lakehouse tables needing attention | [references/operations.md](references/operations.md) |

Operations reference index

Read `references/operations.md` first for any operations request, then open the matching leaf directly from this index. Do not chain from links inside a leaf; for composite requests, follow `scenarios.md` only to the additional leaves that this index links directly.

| Request | Read this leaf reference | |---|---| | composite operations scenarios such as why is my warehouse slow, performance degradation, optimization, or what are people running | [references/operations/scenarios.md](references/operations/scenarios.md) | | slow-query summaries, top users, recent queries, pattern search, runtime profiles, cluster-key candidates | [references/operations/query-reference.md](references/operations/query-reference.md) | | failed or canceled requests, error codes, recurring non-successful query shapes | [references/operations/failure-analysis.md](references/operations/failure-analysis.md) | | SQL pool pressure windows and overlapping requests | [references/operations/pool-pressure.md](references/operations/pool-pressure.md) | | CPU concentration, regressions, repeated expensive queries, cache interpretation | [references/operations/resource-consumers.md](references/operations/resource-consumers.md) | | Lakehouse Delta file health and tables needing maintenance | [references/operations/lakehouse-health.md](references/operations/lakehouse-health.md) | | Capacity Metrics CU spike, costly item, SQL query/user correlation | [references/operations/capacity-metrics-correlation.md](references/operations/capacity-metrics-correlation.md) — start at section 1 | | custom SQL pool recommendation for an already identified SQL endpoint | [references/operations/capacity-metrics-correlation.md](references/operations/capacity-metrics-correlation.md) — skip FabricIQ and start at section 6 |

Mode boundary rule

Classify by **intent**, not by endpoint — all three modes issue the same `execute_query` call.

• A schema-discovery `SELECT` run to plan a `CREATE TABLE` belongs to `authoring`, even though it only reads.
• A `SELECT` that answers the user's question is `consumption`.
• A query against `queryinsights.*` or a supported diagnostic such as Lakehouse `sys.sp_get_table_health_metrics` is `operations`; a `SELECT` against user tables is not, however slow it is.

`consumption` and `operations` are read-only. 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 in