Sqldw CLI

MicrosoftOfficialPublished by Microsoft

Skill
Tool integration
Data and AI
MIT
No issues found

From the author

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.

— the description by Microsoft

AutoGineer summary

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

The sqldw-cli skill provides a structured interface for interacting with Microsoft Fabric data storage items, including Warehouses, Lakehouse SQL analytics endpoints, and Mirrored Databases. It operates through three distinct modes—authoring, consumption, and operations—to handle T-SQL execution, data ingestion, and performance diagnostics. The skill relies on the fabric-sqlendpoint-execute_query MCP tool for data-plane operations and requires users to consult specific mode references to ensure correct T-SQL syntax and operational constraints.

What it does

Executes DDL and DML statements for schema management and data manipulation in Fabric Warehouses.
Supports data ingestion via COPY INTO and OPENROWSET patterns.
Provides read-only querying capabilities for data exploration and metadata discovery.
Enables performance diagnostics using Query Insights and capacity metrics correlation.
Facilitates Lakehouse table health monitoring and diagnostic reporting.
Dispatches requests to specialized modes based on user intent to ensure safe and accurate execution.

When to use it

When you need to create, modify, or drop tables and schemas within a Fabric Warehouse.
When performing bulk data ingestion from external storage into a Warehouse.
When querying data or metadata from a Warehouse, Lakehouse SQL endpoint, or Mirrored Database.
When investigating performance issues, such as slow queries or CU spikes, using diagnostic views.
When correlating capacity consumption with specific SQL queries or users.

Advantages

Centralizes management of diverse Fabric SQL-based data items under a single skill.
Enforces mode-specific safety boundaries to prevent accidental mutations in read-only contexts.
Provides clear diagnostic paths for performance tuning and capacity management.
Standardizes T-SQL execution through a dedicated MCP tool interface.
Includes mandatory telemetry headers for consistent tracking across Fabric API calls.

Usage examples

“How many rows are in the nyctlc table in SkillsTestWarehouse?”: The agent selects the consumption mode, reads the consumption reference, and executes a SELECT COUNT(*) query via the MCP tool to return the exact row count.
“Create dbo.Orders in the warehouse with OrderId, CustomerId and OrderDate.”: The agent selects the authoring mode, reads the authoring reference, executes the CREATE TABLE statement, and performs a readback query to confirm the table exists.
“Which queries are slowest, and which tables should I cluster?”: The agent selects the operations mode, reads the operations reference, and executes diagnostic queries against queryinsights to identify slow-running patterns.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/microsoft/sqldw-cli/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip sqldw-cli.zip -d .agents/skills
```

Documentation by Microsoft

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
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 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
`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
`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

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
slow-query summaries, top users, recent queries, pattern search, runtime profiles, cluster-key candidates	references/operations/query-reference.md
failed or canceled requests, error codes, recurring non-successful query shapes	references/operations/failure-analysis.md
SQL pool pressure windows and overlapping requests	references/operations/pool-pressure.md
CPU concentration, regressions, repeated expensive queries, cache interpretation	references/operations/resource-consumers.md
Lakehouse Delta file health and tables needing maintenance	references/operations/lakehouse-health.md
Capacity Metrics CU spike, costly item, SQL query/user correlation	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 — 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 instead of guessing.

Terminal write — the step you must not skip

Reading the reference and drafting the T-SQL is NOT completing the task. If you did not send the statement, nothing changed — say so explicitly rather than reporting success.

Mode	Terminal write
`authoring`	The DDL/DML itself, sent through `execute_query`. Follow it with a readback in a second call (`SELECT ... FROM INFORMATION_SCHEMA.TABLES` after CREATE, `SELECT COUNT()` after DML) and report the object you created or changed under the name the user asked for*. Only a Warehouse accepts table DDL/DML — see the mode reference for what a Lakehouse SQL endpoint and a Mirrored Database allow.
`consumption`	none — this mode is read-only
`operations`	none — read-only, but you must still run the diagnostic statements: every figure comes from a `SELECT` or documented read-only diagnostic procedure executed in the turn you report it, cited inline with its source view or procedure, never carried forward from an earlier turn. The only allowed diagnostic `EXEC` is `sys.sp_get_table_health_metrics` on a Lakehouse SQL analytics endpoint. Never execute `ALTER`, `CREATE` or `DROP` yourself, even when the diagnosis is certain.

`consumption` and `operations` reporting

Neither read-only mode has a terminal write, so its deliverable is the answer itself. Run the query against the live endpoint and report the real rows — a summary of the reference does not answer the request.

In operations, name the source view, catalog, or procedure each figure came from right next to it (for example 2,140 ms (queryinsights.long_running_queries) or 268 files (sys.sp_get_table_health_metrics)), including when the answer is zero rows. Re-run the diagnostic in the turn you report it rather than restating an earlier turn's output. Never fabricate, assume or infer diagnostic numbers.

Shared essentials (all modes)

Every mode reaches the data plane the same way. Resolve the workspace and item first, then send T-SQL through the MCP tool.

Execution surface — `fabric-sqlendpoint-execute_query`

All T-SQL runs through the fabric-sqlendpoint-execute_query MCP tool. For SQL data-plane execution this skill supersedes the COMMON-CLI SQL/TDS guidance — use the MCP tool, not sqlcmd, unless you are explicitly on the documented Legacy CLI Fallback path (see the mode reference). az rest stays the right tool for control-plane discovery.

fabric-sqlendpoint-execute_query(workspaceId, itemId, query)

Preflight, before the first operation of any mode: confirm a tool whose name ends in execute_query is in your tool list. It comes from the fabric-sqlendpoint MCP server, registered by a Fabric skills plugin or this repo's .mcp.json. The concrete name may be prefixed (fabric-sqlendpoint-execute_query, sqlendpoint-global-execute_query) — invoke the name you actually see. If none is present, say so, then fall back to the Legacy CLI Fallback (TDS client) documented in the mode reference; tell the user they can register the server for the primary path — see mcp-setup/. Exception: the Capacity Metrics correlation workflow is intentionally limited to the existing FabricIQ and SQL Endpoint MCP surfaces; if SQL Endpoint MCP is unavailable, report that phase as blocked and do not use the legacy fallback.
itemId is a GUID, never an FQDN or -d <DatabaseName>. For a Warehouse or a Mirrored Database use the item id; for a Lakehouse use properties.sqlEndpointProperties.id, not the Lakehouse item id.
One T-SQL batch per call. No GO separators, no sqlcmd meta-commands (:setvar, :r, -i). Split multi-batch work into separate calls. Only the last result set comes back.
Results cap at 10,000 rows and queries time out at 300s, with a 20 requests/min rate limit. Use TOP N, WHERE or aggregation; exactly 10,000 rows means the result was truncated. These are observed defaults, not a documented contract.

Common references

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
Fabric Control-Plane API via `az rest`	COMMON-CLI.md	Always pass `--resource`; pagination and LRO helpers
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.
For a focused operations request, read its one matching leaf after references/operations.md. For a composite request, read references/operations/scenarios.md, then each focused leaf named by that scenario; read every file once in full.
Resolve workspace and item ids by listing and filtering, never by guessing a GUID.
Execute T-SQL through fabric-sqlendpoint-execute_query whenever that tool is available; drop to the Legacy CLI Fallback documented in the mode reference only when it is not.
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 statements against the live endpoint and report the real results. Quoting what the reference says instead of executing it does not answer the request.
Produce every artefact the user asked for, under the name they used, and keep its heading even when the finding is "none", "zero rows" or "not applicable".

PREFER

The narrowest mode that satisfies the request.
Reading exactly one mode reference plus the minimum directly indexed operations leaves required by the selected focused or composite scenario.
Reporting the mode you chose in your first response so the user can correct you.
Labelling queries with OPTION (LABEL = '...') so the run is traceable in Query Insights.
Consolidating related statements into fewer calls — the rate limit is per identity, not per query.

AVOID

Acting from this dispatcher alone — it intentionally omits the T-SQL surface area, the DDL constraints and the diagnostic query shapes.
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 (consumption, operations).
Unbounded SELECT * — it silently truncates at 10,000 rows.
Loading a different skill for work this skill already owns (see CRITICAL NOTES 3).

Examples

User request	Mode	Reference to read
"How many rows are in the nyctlc table in SkillsTestWarehouse?"	`consumption`	references/consumption.md
"Create dbo.Orders in the warehouse with OrderId, CustomerId and OrderDate."	`authoring`	references/authoring.md
"Load Files/nyctlc_sample.csv from OneLake into the warehouse with COPY INTO."	`authoring`	references/authoring.md
"Which queries are slowest, and which tables should I cluster?"	`operations`	references/operations.md
"Show me the average trip distance per vendor from the lakehouse SQL endpoint."	`consumption`	references/consumption.md

Files

ATTRIBUTION.mdAdded by AutoGineer863 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md14.2 KiB
apm.yml608 B
references/authoring.md26.7 KiB
references/authoring/authoring-cli-quickref.md9.6 KiB
references/authoring/authoring-script-templates.md7.3 KiB
references/consumption.md20.6 KiB
references/consumption/consumption-cli-quickref.md3.9 KiB
references/consumption/discovery-queries.md5.9 KiB
references/consumption/script-templates.md4.9 KiB
references/operations.md18.6 KiB
references/operations/capacity-metrics-correlation.md19.2 KiB
references/operations/failure-analysis.md7.0 KiB
references/operations/lakehouse-health.md2.6 KiB
references/operations/pool-pressure.md4.0 KiB
references/operations/query-reference.md17.8 KiB
references/operations/resource-consumers.md7.6 KiB
references/operations/scenarios.md8.5 KiB

references/consumption.md

MODE-CRITICAL NOTES (consumption mode)
This mode is read-only. Run SELECT and catalog queries only — no CREATE, ALTER, DROP, INSERT, UPDATE, DELETE, MERGE, TRUNCATE or COPY INTO. If the user asks for a write, refuse the mutation in the final answer and name sqldw-cli authoring mode as a separate follow-up request rather than performing it.
The deliverable is the answer, not the reading. Run the query against the live endpoint and report the real rows; a summary of this reference does not answer the request.

sqldw-cli consumption mode — Fabric Warehouse, Lakehouse SQL Endpoint and Mirrored Database Querying

⚠️ SQL Execution Override: For SQL data-plane execution, this skill supersedes COMMON-CLI SQL/TDS guidance. Use MCP fabric-sqlendpoint-execute_query (see Tool Stack) unless explicitly using Legacy CLI Fallback.

Task	Reference	Notes
Finding Workspaces and Items in Fabric	COMMON-CLI.md § Finding Workspaces and Items in Fabric	Mandatory — READ link first [needed for finding workspace id by its name or item id by its name, item type, and workspace id]
Fabric Topology & Key Concepts	COMMON-CORE.md § Fabric Topology & Key Concepts
Environment URLs	COMMON-CORE.md § Environment URLs
Authentication & Token Acquisition	COMMON-CORE.md § Authentication & Token Acquisition	Wrong audience = 401; read before any auth issue
Core Control-Plane REST APIs	COMMON-CORE.md § Core Control-Plane REST APIs	Includes pagination, LRO polling, and rate-limiting patterns
OneLake Data Access	COMMON-CORE.md § OneLake Data Access	Requires `storage.azure.com` token, not Fabric token
Job Execution	COMMON-CORE.md § Job Execution
Capacity Management	COMMON-CORE.md § Capacity Management
Gotchas, Best Practices & Troubleshooting	COMMON-CORE.md § Gotchas, Best Practices & Troubleshooting
Tool Selection Rationale	COMMON-CLI.md § Tool Selection Rationale
Authentication Recipes	COMMON-CLI.md § Authentication Recipes	`az login` flows and token acquisition
Fabric Control-Plane API via `az rest`	COMMON-CLI.md § Fabric Control-Plane API via az rest	Always pass `--resource`; includes pagination and LRO helpers
OneLake Data Access via `curl`	COMMON-CLI.md § OneLake Data Access via curl	Use `curl` not `az rest` (different token audience)
SQL / TDS Data-Plane Access	SKILL.md § Tool Stack	`fabric-sqlendpoint-execute_query` MCP tool — replaces sqlcmd
Job Execution (CLI)	COMMON-CLI.md § Job Execution
OneLake Shortcuts	COMMON-CLI.md § OneLake Shortcuts
Capacity Management (CLI)	COMMON-CLI.md § Capacity Management
Composite Recipes	COMMON-CLI.md § Composite Recipes
Gotchas & Troubleshooting (CLI-Specific)	COMMON-CLI.md § Gotchas & Troubleshooting (CLI-Specific)	`az rest` audience, shell escaping, token expiry
Quick Reference	COMMON-CLI.md § Quick Reference	`az rest` template + token audience/tool matrix
Item-Type Capability Matrix	SQLDW-CONSUMPTION-CORE.md § Item-Type Capability Matrix	Read first — shows what's read-only (SQLEP) vs read-write (DW)
Connection Fundamentals	SQLDW-CONSUMPTION-CORE.md § Connection Fundamentals	TDS, port 1433, Entra-only, no MARS
Supported T-SQL Surface Area (Consumption Focus)	SQLDW-CONSUMPTION-CORE.md § Supported T-SQL Surface Area	Read before writing T-SQL — includes data types (no `nvarchar`/`datetime`/`money`)
Read-Side Objects You Can Create	SQLDW-CONSUMPTION-CORE.md § Read-Side Objects You Can Create	Views, TVFs, scalar UDFs, procedures
Temporary Tables	SQLDW-CONSUMPTION-CORE.md § Temporary Tables	Use `DISTRIBUTION = ROUND_ROBIN` for INSERT INTO SELECT support
Cross-Database Queries	SQLDW-CONSUMPTION-CORE.md § Cross-Database Queries	3-part naming, same workspace
Security for Consumption	SQLDW-CONSUMPTION-CORE.md § Security for Consumption	GRANT/DENY, RLS, CLS, DDM
Monitoring and Diagnostics	SQLDW-CONSUMPTION-CORE.md § Monitoring and Diagnostics	Includes query labels; DMVs (live) + `queryinsights.*` (30-day history)
Performance: Best Practices and Troubleshooting	SQLDW-CONSUMPTION-CORE.md § Performance: Best Practices and Troubleshooting	Statistics, caching, clustering, query tips
REST API: Refresh SQL Endpoint Metadata	SQLDW-CONSUMPTION-CORE.md § REST API: Refresh SQL Endpoint Metadata	Force metadata sync when SQLEP data is stale after ETL
System Catalog Queries (Metadata Exploration)	SQLDW-CONSUMPTION-CORE.md § System Catalog Queries	`sys.tables`, `sys.columns`, `sys.views`, `sys.stats`
Common Consumption Patterns (End-to-End Examples)	SQLDW-CONSUMPTION-CORE.md § Common Consumption Patterns	Reporting views, cross-DB analytics, temp table staging
Gotchas and Troubleshooting Reference	SQLDW-CONSUMPTION-CORE.md § Gotchas and Troubleshooting Reference	18 numbered issues with cause + resolution
Quick Reference: Consumption Capabilities by Scenario	SQLDW-CONSUMPTION-CORE.md § Quick Reference: Consumption Capabilities	Scenario → approach lookup
Schema and Object Discovery	discovery-queries.md § Schema and Object Discovery	Tables, columns, views, functions, procedures, cross-DB
Security Discovery	discovery-queries.md § Security Discovery
Statistics and Performance Metadata	discovery-queries.md § Statistics and Performance Metadata
Data Export Workflow	script-templates.md § Data Export Workflow	Query to CSV + parameterized date range export
Schema Discovery Workflow	script-templates.md § Schema Discovery Workflow	Full schema report via MCP
Performance Investigation Workflow	script-templates.md § Performance Investigation Workflow	Active queries, slow query analysis
Tool Stack	SKILL.md § Tool Stack	`fabric-sqlendpoint-execute_query` MCP tool + `az` CLI
Connection	SKILL.md § Connection
Agentic Exploration ("Chat With My Data")	SKILL.md § Agentic Exploration	Start here for data exploration
Script Generation	consumption-cli-quickref.md § Script Generation	When to emit a standalone bash/PowerShell script; `az rest` discovery + Legacy CLI Fallback
Monitoring and Performance	consumption-cli-quickref.md § Monitoring and Performance	Active queries DMV (read-only; session termination is out of scope)
Gotchas, Rules, Troubleshooting	SKILL.md § Gotchas, Rules, Troubleshooting	MUST DO / AVOID / PREFER checklists
Agent Integration Notes	consumption-cli-quickref.md § Agent Integration Notes	Per-agent CLI tips

Tool Stack

Tool	Role	Install
`fabric-sqlendpoint-execute_query` MCP tool	Primary: Execute T-SQL queries against Fabric SQL Endpoints. Returns CSV results. Auth handled by MCP protocol.	No install — server-side. Requires MCP server registration (see below).
`az` CLI	Auth (`az login`), Fabric REST for workspace/item discovery.	Pre-installed in most dev environments
`jq`	Parse JSON from `az rest`	Pre-installed or trivial

IMPORTANT — MCP vs sqlcmd: This skill uses the fabric-sqlendpoint-execute_query MCP tool for all T-SQL execution. Do not use COMMON-CLI SQL/TDS/sqlcmd sections for query execution. Those references apply only for az rest control-plane patterns.

Agent preflight — verify before first SQL operation:
Confirm the fabric-sqlendpoint-execute_query tool is available in your tool list. This tool is provided by the fabric-sqlendpoint MCP server, which is registered either by installing a Fabric skills plugin (the path for end users) or via this repo's .mcp.json — other MCP clients may register it through their own configuration.
If no tool matches, the user must register the Fabric SQL Endpoint MCP server. See MCP setup for registration instructions.
Global URL: https://api.fabric.microsoft.com/v1/mcp/dataPlane/sqlEndpoint
Item-scoped URL: https://api.fabric.microsoft.com/v1/mcp/dataPlane/workspaces/{workspaceId}/items/{itemId}/sqlEndpoint

MCP Tool Signature

fabric-sqlendpoint-execute_query(workspaceId, itemId, query)

Tool name may differ: execute_query is the logical operation. Depending on how the server is registered, the concrete tool name in your tool list may be prefixed (e.g. fabric-sqlendpoint-execute_query or sqlendpoint-global-execute_query). Invoke the concrete name shown in your tool list, always passing workspaceId, itemId, and query.

Parameter	Type	Description
`workspaceId`	string (UUID)	The workspace GUID containing the target item
`itemId`	string (UUID)	The Fabric item GUID to query. For a Warehouse or Mirrored Database, use the item id. For a Lakehouse, use its SQL analytics endpoint id (`properties.sqlEndpointProperties.id`) — not the Lakehouse item id.
`query`	string	T-SQL query text (single batch — no `GO` separators or sqlcmd meta-commands)

Returns: CSV resource (RFC 4180) with tabular results + metadata text ("Query returned N rows.").

Batch guidance: Multiple statements (e.g., SET NOCOUNT ON; SELECT ...) are allowed in a single call as long as there are no GO separators. Only the last result set is returned. For independent read queries, prefer separate fabric-sqlendpoint-execute_query calls for clearer error handling.

MCP Limits

Limit	Value	Notes
Max rows	10,000	Results are truncated beyond this. Use `TOP`, filters, or aggregations.
Query timeout	300 seconds	Long-running queries fail with timeout error.
Rate limit	20 requests/min per identity	HTTP 429 returned when exceeded. Retry after backoff.

These values are observed defaults, not a documented contract — the MCP service can change them. Treat them as guidance and confirm the current behavior from live 429 / timeout / truncation responses (or Microsoft Learn, if/when published) rather than relying on the exact numbers.

Supported Item Types

Item Type	itemId Source	Read Queries	DML (INSERT/UPDATE/DELETE)
Warehouse	`GET /v1/workspaces/{wId}/warehouses` → item `id`	✅	✅
Lakehouse SQL Endpoint	`GET /v1/workspaces/{wId}/lakehouses` → `properties.sqlEndpointProperties.id` (not the lakehouse `id`)	✅	❌ (read-only)
Mirrored Database	`GET /v1/workspaces/{wId}/mirroredDatabases` → item `id`	✅	❌ (read-only)

Connection

Discover workspaceId and itemId

You need the workspace GUID and item GUID to call fabric-sqlendpoint-execute_query. Discover them via the Fabric REST API:

# 1. Find workspace ID by name (capture into WS_ID for the next calls)
WS_ID=$(az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces" \
  --query "value[?displayName=='MyWorkspace'].id" --output tsv)
echo "Workspace ID: $WS_ID"

# 2. Find warehouse item ID by name
az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/warehouses" \
  --query "value[?displayName=='MyWarehouse'].id" --output tsv
# For a Lakehouse, pass its SQL analytics endpoint id — NOT the lakehouse item id
az rest --method get \
  --resource "https://api.fabric.microsoft.com" \
  --url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/lakehouses" \
  --query "value[?displayName=='MyLakehouse'].properties.sqlEndpointProperties.id" --output tsv

Execute a Query

Once you have workspaceId and itemId, call the MCP tool:

fabric-sqlendpoint-execute_query(
  workspaceId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  itemId: "11111111-2222-3333-4444-555555555555",
  query: "SELECT TOP 10 * FROM dbo.FactSales"
)

No additional connection setup needed — authentication is handled transparently by the MCP protocol.

Agentic Exploration ("Chat With My Data")

Schema Discovery Sequence

Run these in order to understand what's in the endpoint. See references/discovery-queries.md for extended discovery queries.

# 1. List schemas
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT schema_name FROM INFORMATION_SCHEMA.SCHEMATA ORDER BY schema_name")

# 2. List tables and views
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT table_schema, table_name, table_type FROM INFORMATION_SCHEMA.TABLES ORDER BY table_schema, table_name")

# 3. Columns for a table
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT column_name, data_type, character_maximum_length, is_nullable FROM INFORMATION_SCHEMA.COLUMNS WHERE table_schema='dbo' AND table_name='FactSales' ORDER BY ordinal_position")

# 4. Preview rows
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT TOP 5 * FROM dbo.FactSales")

# 5. Row counts
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT s.name AS [schema], t.name AS [table], SUM(p.rows) AS row_count FROM sys.tables t JOIN sys.schemas s ON t.schema_id=s.schema_id JOIN sys.partitions p ON t.object_id=p.object_id AND p.index_id IN (0,1) GROUP BY s.name, t.name ORDER BY row_count DESC")

# 6. Programmability objects (views, functions, procedures)
fabric-sqlendpoint-execute_query(workspaceId, itemId, "SELECT name, type_desc FROM sys.objects WHERE type IN ('V','FN','IF','P','TF') ORDER BY type_desc, name")

Agentic Workflow

Discover → Run Steps 1–3 to understand available tables/columns.
Sample → SELECT TOP 5 on relevant tables.
Formulate → Write T-SQL using SQLDW-CONSUMPTION-CORE.md Supported T-SQL Surface Area.
Execute → Call fabric-sqlendpoint-execute_query(workspaceId, itemId, query).
Iterate → Refine based on results.
Present → Show results or generate follow-up queries.

Gotchas, Rules, Troubleshooting

For full T-SQL/platform gotchas: SQLDW-CONSUMPTION-CORE.md Gotchas and Troubleshooting Reference.

MUST DO

Verify fabric-sqlendpoint-execute_query MCP tool is available — check tool list before first operation. If unavailable, instruct user to register the MCP server.
Always use TOP or WHERE filters — the MCP tool returns a maximum of 10,000 rows. If exactly 10,000 rows are returned, results are likely truncated.
Use COUNT(*) first for large tables — check row counts before running unbounded SELECTs.
SET NOCOUNT ON; at the start of multi-statement queries — suppresses row-count messages.
Label queries with OPTION (LABEL = 'AGENTCLI_...') for Query Insights tracing.
Send valid T-SQL only — no GO batch separators, no :setvar, no sqlcmd meta-commands. Each fabric-sqlendpoint-execute_query call is a single T-SQL batch.
Use multiple tool calls for multi-batch operations — if you need GO separators, split into separate fabric-sqlendpoint-execute_query calls.

AVOID

sqlcmd — use the fabric-sqlendpoint-execute_query MCP tool instead. Do not shell out to sqlcmd for query execution.
Unbounded SELECT * — will hit the 10,000 row cap. Always use TOP N or WHERE filters.
Rapid-fire sequential queries — rate limit is 20 req/min per identity. Space out calls or consolidate with JOINs/UNION ALL.
DML on Lakehouse/Mirrored DB — these are read-only. DML only works on Warehouse items.
GO separators in query text — not supported. Use separate tool calls for each batch.
MARS — not supported. Each query runs independently.
Hardcoded item IDs — discover via REST API (Connection section).

PREFER

fabric-sqlendpoint-execute_query MCP tool over any CLI tool for T-SQL execution.
TOP N on exploration queries — avoid hitting row limits.
Consolidating related queries into single SELECTs with JOINs to reduce rate-limit pressure.
az rest for Fabric REST API operations — workspace/item discovery, capacity management.
Aggregate queries (COUNT, SUM, AVG, GROUP BY) over full table scans.
ORDER BY with TOP for deterministic results.

TROUBLESHOOTING

Symptom	Cause	Fix
MCP tool not available	MCP server not registered	Register `https://api.fabric.microsoft.com/v1/mcp/dataPlane/sqlEndpoint` in MCP client config
HTTP 401 / Unauthorized	Auth token expired or invalid	Re-authenticate (depends on MCP client — may need `az login` refresh)
HTTP 403 / Forbidden	Insufficient permissions on workspace/item	Verify user has Viewer+ role on the workspace/item
HTTP 404 / Not Found	Wrong workspaceId/itemId, or feature not enabled	Verify IDs via REST API; check if MCP feature is enabled for the tenant
HTTP 429 / Too Many Requests	Rate limit exceeded (20 req/min)	Wait and retry with backoff; consolidate queries
Query timeout (300s)	Query too complex or data too large	Simplify query, add filters, use `TOP`
Exactly 10,000 rows returned	Result truncation	Add `TOP N` or `WHERE` filters; use `COUNT(*)` to check total
"Invalid workspaceId/itemId"	Malformed UUID	Verify UUIDs are correct format (8-4-4-4-12 hex digits)
SQL error in response	T-SQL syntax error or invalid object	Fix T-SQL; verify table/column names via schema discovery
No rows but data exists	RLS filtering	Check `USER_NAME()`, verify RLS policies
`Invalid object name 'queryinsights...'`	New warehouse < 2 min old	Wait ~2 minutes

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.

Needs: Needs an MCP server

Security

No issues found by our static scan· No issues found

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/sqldw-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 sqldw-cli.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Microsoft

Fabric Warehouse and SQL Endpoints — CLI Skill

Mode selection

Operations reference index

Mode boundary rule

Terminal write — the step you must not skip

consumption and operations reporting

Shared essentials (all modes)

Execution surface — fabric-sqlendpoint-execute_query

Common references

Rules

MUST

PREFER

AVOID

Examples

Files

references/consumption.md

sqldw-cli consumption mode — Fabric Warehouse, Lakehouse SQL Endpoint and Mirrored Database Querying

Table of Contents

Tool Stack

MCP Tool Signature

MCP Limits

Supported Item Types

Connection

Discover workspaceId and itemId

Execute a Query

Agentic Exploration ("Chat With My Data")

Schema Discovery Sequence

Agentic Workflow

Gotchas, Rules, Troubleshooting

MUST DO

AVOID

PREFER

TROUBLESHOOTING

Requirements and compatibility

Security

Attribution and licence

Related skills

Anndata

Liteparse

Usfiscaldata

Geopandas

Markitdown

Zarr Python

Download ZIP

`consumption` and `operations` reporting

Execution surface — `fabric-sqlendpoint-execute_query`