From fabric-skills
Analyzes Microsoft Fabric Data Warehouse performance via sqlcmd CLI and queryinsights views. Diagnoses slow queries, SQL pool pressure, cache coldness, and recommends clustering keys.
npx claudepluginhub microsoft/skills-for-fabric --plugin skills-for-fabricThis skill uses the workspace's default tool permissions.
> **Update Check — ONCE PER SESSION (mandatory)**
Executes read-only T-SQL queries against Fabric Data Warehouse, Lakehouse SQL Endpoints, and Mirrored Databases via CLI. For row counts, SELECTs, filtering, aggregation, schema discovery, T-SQL generation, performance monitoring, and CSV/JSON exports.
Optimizes Snowflake queries using clustering keys, materialized views, caching, query profiling, and warehouse tuning. Identifies slow queries and bottlenecks via QUERY_HISTORY.
Query and analyze data in Azure Data Explorer (Kusto/ADX) using KQL for log analytics, telemetry, and time series analysis.
Share bugs, ideas, or general feedback.
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-updatesskill.- 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
- 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
This skill provides performance analysis, deep diagnostics, and optimization guidance for Microsoft Fabric Data Warehouse via sqlcmd and the built-in queryinsights views. All queries are read-only.
For tool installation and authentication setup, see COMMON-CLI.md § Authentication Recipes and COMMON-CLI.md § SQL / TDS Data-Plane Access.
Monitoring-specific requirements:
queryinsights views)queryinsights views retain 30 days; data appears with up to 15 min delay)| 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 |
| Capacity Management | COMMON-CORE.md § Capacity Management | |
| Gotchas, Best Practices & Troubleshooting (Platform) | 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 |
| SQL / TDS Data-Plane Access | COMMON-CLI.md § SQL / TDS Data-Plane Access | sqlcmd (Go) connect, query, CSV export |
| 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 |
| Connection Fundamentals | SQLDW-CONSUMPTION-CORE.md § Connection Fundamentals | TDS, port 1433, Entra-only, no MARS |
| Monitoring and Diagnostics | SQLDW-CONSUMPTION-CORE.md § Monitoring and Diagnostics | 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 |
| Gotchas and Troubleshooting (Consumption) | SQLDW-CONSUMPTION-CORE.md § Gotchas and Troubleshooting Reference | 18 numbered issues with cause + resolution |
| Data Ingestion (DW Only) | SQLDW-AUTHORING-CORE.md § Data Ingestion (DW Only) | COPY INTO, OPENROWSET, method comparison |
| Query Reference | query-reference.md | T-SQL queries, parameters, and example output for all analyses |
| Composite Recipes | COMMON-CLI.md § Composite Recipes | |
| Item-Type Capability Matrix | SQLDW-CONSUMPTION-CORE.md § Item-Type Capability Matrix | Warehouses only — queryinsights not available on SQLEP |
| Prerequisites | SKILL.md § Prerequisites | Tools, auth, workspace role |
| Tool Stack | SKILL.md § Tool Stack | |
| Connection | SKILL.md § Connection | |
| Performance Analysis | SKILL.md § Performance Analysis | Long-running queries, resource consumers, user insights, baselines |
| Deep Diagnostics | SKILL.md § Deep Diagnostics | Pressure windows, cache warmth, cluster keys |
| Fabric DW Constraints | SKILL.md § Fabric DW Constraints | NEVER recommend unsupported features |
| Best Practices | SKILL.md § Best Practices | Monitoring-specific guidance |
| Agentic Workflows | SKILL.md § Agentic Workflows | Common investigation patterns |
| Gotchas, Rules, Troubleshooting | SKILL.md § Gotchas, Rules, Troubleshooting | MUST DO / AVOID / PREFER checklists |
| Examples | SKILL.md § Examples | Prompt/response pairs |
For installation and setup, see Prerequisites.
| Tool | Role |
|---|---|
sqlcmd (Go) | Execute monitoring T-SQL queries via Entra ID auth (-G) |
az CLI | Token acquisition, Fabric REST for endpoint discovery |
jq | Parse JSON from az rest |
For authentication recipes (interactive, service principal, CI/CD), see COMMON-CLI.md § Authentication Recipes.
Per COMMON-CLI.md Discovering Connection Parameters via REST:
WS_ID="<workspaceId>"
ITEM_ID="<warehouseId>"
# Warehouse
az rest --method get \
--resource "https://api.fabric.microsoft.com" \
--url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/warehouses/$ITEM_ID" \
--query "properties.connectionString" --output tsv
Result: <uniqueId>.datawarehouse.fabric.microsoft.com
sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>" -G \
-Q "SELECT TOP 5 * FROM queryinsights.exec_requests_history ORDER BY total_elapsed_time_ms DESC"
FABRIC_SERVER="<endpoint>.datawarehouse.fabric.microsoft.com"
FABRIC_DB="<DatabaseName>"
SQLCMD="sqlcmd -S $FABRIC_SERVER -d $FABRIC_DB -G"
$SQLCMD -Q "SELECT TOP 5 * FROM queryinsights.long_running_queries ORDER BY last_run_total_elapsed_time_ms DESC"
# PowerShell
$s = "<endpoint>.datawarehouse.fabric.microsoft.com"; $db = "<DatabaseName>"
sqlcmd -S $s -d $db -G -Q "SELECT TOP 5 * FROM queryinsights.exec_requests_history ORDER BY total_elapsed_time_ms DESC"
All SQL queries, parameters, return fields, and response formatting are in query-reference.md.
Find the slowest queries from queryinsights.long_running_queries. See query-reference.md § Long-Running Queries Summary for SQL and formatting.
Find CPU- and storage-heavy queries from queryinsights.exec_requests_history. See query-reference.md § Top Resource Consumers for SQL, thresholds, and formatting.
Recommendation thresholds:
Analyze user activity and query patterns. See query-reference.md § Top Users Insights for SQL and classification logic.
Detect performance regressions by comparing recent window against historical baseline. See query-reference.md § Compare Recent vs Baseline for SQL and formatting.
Retrieve the most recently executed queries. See query-reference.md § Recent Queries for SQL.
Search historical query patterns by table name, column, or keyword. See query-reference.md § Search Query Patterns for SQL.
All SQL queries for diagnostics are in query-reference.md.
See query-reference.md § Long-Running Query Analysis for SQL.
Analysis guidance — when reviewing slow queries, check:
data_scanned_remote_storage_mb → data layout issues (run OPTIMIZE, consider clustering)allocated_cpu_time_ms relative to elapsed → CPU-bound (simplify joins, reduce columns)Identify SQL pool pressure events using queryinsights.sql_pool_insights and correlate with the heaviest queries running during those windows. See query-reference.md § Pressure Window Analysis for the two-step SQL.
Usage: Step 1 returns pressure windows with window_start and window_end timestamps. Substitute those actual timestamp values into Step 2's WHERE clause to find overlapping queries.
Global recommendations — based on aggregate pressure analysis:
See query-reference.md § Cache Warmth Analysis for SQL.
Classification logic — for each execution, compute total_mb = remote + memory + disk:
result_cache_hit = 1 → cachedremote_mb / total_mb > 0.8 → cold (>80% from remote storage)(memory_mb + disk_mb) / total_mb > 0.8 → warm (>80% from cache)Recommendations:
ALTER DATABASE SET RESULT_SET_CACHING ON;GETDATE()/GETUTCDATE() or volatile functions that bust the cache keySee query-reference.md § Cluster Key Recommendations for SQL.
Key rules:
WHERE predicates benefit from clustering — equality JOIN ON conditions do notWITH (CLUSTER BY (...)) — ALTER TABLE is not supportedTo apply clustering — see query-reference.md § Cluster Key Recommendations for CTAS creation, sp_rename table swap, and verification SQL.
Note: Fabric does not support
ALTER TABLE SET DATA_CLUSTERING_KEYorRENAME OBJECT. Always use CTAS withWITH (CLUSTER BY (...))andsp_renamefor table swaps.
NEVER recommend features not supported in Fabric Data Warehouse. Always consult this list before making optimization suggestions.
| Do NOT Recommend | Why | Recommend Instead |
|---|---|---|
| Nonclustered indexes | Not supported | V-Order, column pruning, predicate pushdown |
| Materialized views | Not supported | Standard views or result set caching |
| Index hints (FORCESEEK/FORCESCAN) | Not supported | Simplify query structure |
| Multi-column statistics | Not supported | Single-column statistics on key columns |
ALTER TABLE SET DATA_CLUSTERING_KEY | Not supported | CTAS with WITH (CLUSTER BY (...)) |
RENAME OBJECT | Not supported | EXEC sp_rename 'schema.old', 'new' |
| Change isolation level | Snapshot only | Fabric uses snapshot isolation exclusively |
| CREATE USER | Not supported | Manage users via Fabric workspace |
| Triggers | Not supported | Application logic or Fabric pipelines |
| Recursive CTEs | Not supported | Iterative approach |
| "Enable Query Insights" setting | Query Insights is always on — there is no setting | If access is denied, the user needs Admin or Member workspace role |
For comprehensive Fabric DW best practices, see SQLDW-CONSUMPTION-CORE.md § Performance: Best Practices and Troubleshooting and the Fabric guidelines.
Monitoring-specific best practices:
OPTION (LABEL = 'AGENTCLI_MONITOR_...') for tracing in Query InsightsWHERE predicates to identify cluster key candidates — equality JOIN ON conditions do not benefit from clusteringsys.index_columns.data_clustering_ordinalDATEADD parameters) to match user's investigation scope — don't default to arbitrary windowsFor generic CLI gotchas (connection, auth, shell escaping): see COMMON-CLI.md § Gotchas & Troubleshooting. For T-SQL/platform gotchas: see SQLDW-CONSUMPTION-CORE.md § Gotchas and Troubleshooting Reference.
WITH (CLUSTER BY (...)) — not ALTER TABLEOPTION (LABEL = 'AGENTCLI_MONITOR_...') for Query Insights tracingDATEADD parameters) based on what the user asks forqueryinsights views are always available; permission errors indicate insufficient workspace role (Admin or Member required)SELECT * in monitoring queries — always select specific columnsFor generic connection/auth troubleshooting, see COMMON-CLI.md § Gotchas & Troubleshooting.
| Symptom | Cause | Fix |
|---|---|---|
Invalid object name 'queryinsights...' | New warehouse < 2 min old | Wait ~2 minutes |
Permission errors on queryinsights.* | Insufficient workspace role | Requires Admin or Member role |
| No data in queryinsights views | No recent query activity or < 15 min delay | Wait 15 min after query completion |
| No rows but data exists | RLS filtering | Check USER_NAME(), verify RLS policies |
User: "What are the slowest queries in my warehouse?"
Agent: Runs the long-running queries summary via sqlcmd:
sqlcmd -S "myserver.datawarehouse.fabric.microsoft.com" -d "MyWarehouse" -G -Q "
SELECT TOP 5
left(last_run_command, 80) AS query_preview,
number_of_runs,
last_run_total_elapsed_time_ms,
median_total_elapsed_time_ms
FROM queryinsights.long_running_queries
ORDER BY median_total_elapsed_time_ms DESC
"
The top 5 slowest queries are:
SELECT * FROM FactSales JOIN DimCustomer...— ran 12 times, last took 45,200 ms (median 38,500 ms)SELECT region, SUM(amount)...— ran 8 times, last took 32,100 ms (median 29,000 ms) ...
User: "Is my warehouse slower than last week?"
Agent: Runs the baseline comparison query and presents:
Performance Comparison (last 1h vs 7-day baseline):
- Elapsed time: 2,450 ms avg → 4,100 ms avg (+67.3%)
- CPU consumption: 1,200 ms → 2,800 ms (+133.3%)
- Data scanned: 450 MB → 480 MB (+6.7%)
Significant regression detected. Let me check for pressure events and analyze the heaviest queries...
Then follows up with pressure window and resource consumer queries.
User: "Which tables should I cluster and on what columns?"
Agent: Runs the cluster key recommendation queries and presents:
Recommended Clustering Keys:
Table Recommended Columns Row Count Total Scanned MB dbo.FactSales SaleDate, Region 50M 12,500 MB dbo.FactInventory ProductID, WarehouseID 12M 3,200 MB To apply clustering, use CTAS:
CREATE TABLE dbo.FactSales_clustered WITH (CLUSTER BY (SaleDate, Region)) AS SELECT * FROM dbo.FactSales;