1---
2name: azure-kusto
3description: "Query and analyze data in Azure Data Explorer (Kusto/ADX) using KQL for log analytics, telemetry, and time series analysis. WHEN: KQL queries, Kusto database queries, Azure Data Explorer, ADX clusters, log analytics, time series data, IoT telemetry, anomaly detection."
4license: MIT
5metadata:
6  author: Microsoft
7  version: "1.1.1"
8---
9 
10# Azure Data Explorer (Kusto) Query & Analytics
11 
12Execute KQL queries and manage Azure Data Explorer resources for fast, scalable big data analytics on log, telemetry, and time series data.
13 
14## Skill Activation Triggers
15 
16**Use this skill immediately when the user asks to:**
17- "Query my Kusto database for [data pattern]"
18- "Show me events in the last hour from Azure Data Explorer"
19- "Analyze logs in my ADX cluster"
20- "Run a KQL query on [database]"
21- "What tables are in my Kusto database?"
22- "Show me the schema for [table]"
23- "List my Azure Data Explorer clusters"
24- "Aggregate telemetry data by [dimension]"
25- "Create a time series chart from my logs"
26 
27**Key Indicators:**
28- Mentions "Kusto", "Azure Data Explorer", "ADX", or "KQL"
29- Log analytics or telemetry analysis requests
30- Time series data exploration
31- IoT data analysis queries
32- SIEM or security analytics tasks
33- Requests for data aggregation on large datasets
34- Performance monitoring or APM queries
35 
36## Overview
37 
38This skill enables querying and managing Azure Data Explorer (Kusto), a fast and highly scalable data exploration service optimized for log and telemetry data. Azure Data Explorer provides sub-second query performance on billions of records using the Kusto Query Language (KQL).
39 
40Key capabilities:
41- **Query Execution**: Run KQL queries against massive datasets
42- **Schema Exploration**: Discover tables, columns, and data types
43- **Resource Management**: List clusters and databases
44- **Analytics**: Aggregations, time series, anomaly detection, machine learning
45 
46## Core Workflow
47 
481. **Discover Resources**: List available clusters and databases in subscription
492. **Explore Schema**: Retrieve table structures to understand data model
503. **Query Data**: Execute KQL queries for analysis, filtering, aggregation
514. **Analyze Results**: Process query output for insights and reporting
52 
53## Query Patterns
54 
55### Pattern 1: Basic Data Retrieval
56Fetch recent records from a table with simple filtering.
57 
58**Example KQL**:
59```kql
60Events
61| where Timestamp > ago(1h)
62| take 100
63```
64 
65**Use for**: Quick data inspection, recent event retrieval
66 
67### Pattern 2: Aggregation Analysis
68Summarize data by dimensions for insights and reporting.
69 
70**Example KQL**:
71```kql
72Events
73| summarize count() by EventType, bin(Timestamp, 1h)
74| order by count_ desc
75```
76 
77**Use for**: Event counting, distribution analysis, top-N queries
78 
79### Pattern 3: Time Series Analytics
80Analyze data over time windows for trends and patterns.
81 
82**Example KQL**:
83```kql
84Telemetry
85| where Timestamp > ago(24h)
86| summarize avg(ResponseTime), percentiles(ResponseTime, 50, 95, 99) by bin(Timestamp, 5m)
87| render timechart
88```
89 
90**Use for**: Performance monitoring, trend analysis, anomaly detection
91 
92### Pattern 4: Join and Correlation
93Combine multiple tables for cross-dataset analysis.
94 
95**Example KQL**:
96```kql
97Events
98| where EventType == "Error"
99| join kind=inner (
100    Logs
101    | where Severity == "Critical"
102) on CorrelationId
103| project Timestamp, EventType, LogMessage, Severity
104```
105 
106**Use for**: Root cause analysis, correlated event tracking
107 
108### Pattern 5: Schema Discovery
109Explore table structure before querying.
110 
111**Tools**: `kusto_table_schema_get`
112 
113**Use for**: Understanding data model, query planning
114 
115## Key Data Fields
116 
117When executing queries, common field patterns:
118- **Timestamp**: Time of event (datetime) - use `ago()`, `between()`, `bin()` for time filtering
119- **EventType/Category**: Classification field for grouping
120- **CorrelationId/SessionId**: For tracing related events
121- **Severity/Level**: For filtering by importance
122- **Dimensions**: Custom properties for grouping and filtering
123 
124## Result Format
125 
126Query results include:
127- **Columns**: Field names and data types
128- **Rows**: Data records matching query
129- **Statistics**: Row count, execution time, resource utilization
130- **Visualization**: Chart rendering hints (timechart, barchart, etc.)
131 
132## KQL Best Practices
133 
134**🟢 Performance Optimized:**
135- Filter early: Use `where` before joins and aggregations
136- Limit result size: Use `take` or `limit` to reduce data transfer
137- Time filters: Always filter by time range for time series data
138- Indexed columns: Filter on indexed columns first
139 
140**🔵 Query Patterns:**
141- Use `summarize` for aggregations instead of `count()` alone
142- Use `bin()` for time bucketing in time series
143- Use `project` to select only needed columns
144- Use `extend` to add calculated fields
145 
146**🟡 Common Functions:**
147- `ago(timespan)`: Relative time (ago(1h), ago(7d))
148- `between(start .. end)`: Range filtering
149- `startswith()`, `contains()`, `matches regex`: String filtering
150- `parse`, `extract`: Extract values from strings
151- `percentiles()`, `avg()`, `sum()`, `max()`, `min()`: Aggregations
152 
153## Best Practices
154 
155- Always include time range filters to optimize query performance
156- Use `take` or `limit` for exploratory queries to avoid large result sets
157- Leverage `summarize` for aggregations instead of client-side processing
158- Store frequently-used queries as functions in the database
159- Use materialized views for repeated aggregations
160- Monitor query performance and resource consumption
161- Apply data retention policies to manage storage costs
162- Use streaming ingestion for real-time analytics (< 1 second latency)
163- Integrate with Azure Monitor for operational insights
164 
165## MCP Tools Used
166 
167| Tool | Purpose |
168|------|---------|
169| `kusto_cluster_list` | List all Azure Data Explorer clusters in a subscription |
170| `kusto_database_list` | List all databases in a specific Kusto cluster |
171| `kusto_query` | Execute KQL queries against a Kusto database |
172| `kusto_table_schema_get` | Retrieve schema information for a specific table |
173 
174**Required Parameters**:
175- `subscription`: Azure subscription ID or display name
176- `cluster`: Kusto cluster name (e.g., "mycluster")
177- `database`: Database name
178- `query`: KQL query string (for query operations)
179- `table`: Table name (for schema operations)
180 
181**Optional Parameters**:
182- `resource-group`: Resource group name (for listing operations)
183- `tenant`: Azure AD tenant ID
184 
185## Fallback Strategy: Azure CLI Commands
186 
187If Azure MCP Kusto tools fail, timeout, or are unavailable, use Azure CLI commands as fallback.
188 
189### CLI Command Reference
190 
191| Operation | Azure CLI Command |
192|-----------|-------------------|
193| List clusters | `az kusto cluster list --resource-group <rg-name>` |
194| List databases | `az kusto database list --cluster-name <cluster> --resource-group <rg-name>` |
195| Show cluster | `az kusto cluster show --name <cluster> --resource-group <rg-name>` |
196| Show database | `az kusto database show --cluster-name <cluster> --database-name <db> --resource-group <rg-name>` |
197 
198### KQL Query via Azure CLI
199 
200For queries, use the Kusto REST API or direct cluster URL:
201```bash
202az rest --method post \
203  --url "https://<cluster>.<region>.kusto.windows.net/v1/rest/query" \
204  --body "{ \"db\": \"<database>\", \"csl\": \"<kql-query>\" }"
205```
206 
207### When to Fallback
208 
209Switch to Azure CLI when:
210- MCP tool returns timeout error (queries > 60 seconds)
211- MCP tool returns "service unavailable" or connection errors
212- Authentication failures with MCP tools
213- Empty response when database is known to have data
214 
215## Common Issues
216 
217- **Access Denied**: Verify database permissions (Viewer role minimum for queries)
218- **Query Timeout**: Optimize query with time filters, reduce result set, or increase timeout
219- **Syntax Error**: Validate KQL syntax - common issues: missing pipes, incorrect operators
220- **Empty Results**: Check time range filters (may be too restrictive), verify table name
221- **Cluster Not Found**: Check cluster name format (exclude ".kusto.windows.net" suffix)
222- **High CPU Usage**: Query too broad - add filters, reduce time range, limit aggregations
223- **Ingestion Lag**: Streaming data may have 1-30 second delay depending on ingestion method
224 
225## Use Cases
226 
227- **Log Analytics**: Application logs, system logs, audit logs
228- **IoT Analytics**: Sensor data, device telemetry, real-time monitoring
229- **Security Analytics**: SIEM data, threat detection, security event correlation
230- **APM**: Application performance metrics, user behavior, error tracking
231- **Business Intelligence**: Clickstream analysis, user analytics, operational KPIs