Sqldw Consumption CLI

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

Update Check — ONCE PER SESSION (mandatory) The first time this skill is used in a session, run the check-updates skill before proceeding.

• GitHub Copilot CLI / VS Code: invoke the check-updates skill.
• Claude Code / Cowork / Cursor / Windsurf / Codex: compare local vs remote package.json version.
• Skip if the check was already performed earlier in this session.

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

SQL Endpoint Consumption — CLI Skill

⚠️ 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.

Table of Contents

Tool Stack

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:

1. 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.
2. If no matching tool is found, 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.

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

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

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

1. Discover → Run Steps 1–3 to understand available tables/columns.
2. Sample → SELECT TOP 5 on relevant tables.
3. Formulate → Write T-SQL using SQLDW-CONSUMPTION-CORE.md Supported T-SQL Surface Area.
4. Execute → Call fabric-sqlendpoint-execute_query(workspaceId, itemId, query).
5. Iterate → Refine based on results.
6. 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