Warm Queries Troubleshooting

Warm queries are saved KQL queries with their own API endpoints. They're the bridge between raw data and actionable insights. This guide covers common query issues.

---

Quick Diagnosis

Check these first:

1. Does the surface have data? Test with a simple TableName | take 10
2. Is the KQL syntax correct? Check for common syntax errors
3. Does the time window contain data? Try expanding the range

---

Common Issues

Query Returns Empty Results

Most common causes:

1. Time window too narrow - Data exists but outside your filter
2. Field name typo - KQL is case-sensitive
3. Filter too restrictive - Multiple WHERE clauses eliminating all data

Diagnosis process:

// Step 1: Check if any data exists
YourTable | take 10

// Step 2: Check time range
YourTable | where timestamp > ago(7d) | take 10

// Step 3: Add filters one at a time
YourTable | where timestamp > ago(7d) | where field1 == "value" | take 10

When data disappears, you've found the problematic filter.

Query Has Syntax Error

Symptoms:

• Red error indicator
• Error message about syntax
• Query won't execute

Common KQL syntax issues:

Error	Cause	Fix
"unexpected character"	Wrong quotes or operators	Use double quotes for strings
"column not found"	Typo in field name	Check exact field names
"invalid operator"	Wrong comparison	Use == not =
"cannot convert"	Type mismatch	Check data types

Query Runs Slow

Symptoms:

• Query takes too long
• Timeout errors
• API calls fail

Optimization tips:

// BAD: No time filter (scans everything)
YourTable | where status == "active"

// GOOD: Time filter first (limits scan)
YourTable | where timestamp > ago(1h) | where status == "active"

---

KQL Syntax Help

String Comparisons

// Exact match (case-sensitive)
| where status == "Active"

// Case-insensitive match
| where status =~ "active"

// Contains
| where message contains "error"

// Starts with
| where name startswith "sensor"

Numeric Comparisons

// Greater than
| where temperature > 70

// Range
| where temperature between (60 .. 80)

// Not equal
| where errorCode != 0

Time Filters

// Relative time
| where timestamp > ago(1h)
| where timestamp > ago(7d)

// Specific range
| where timestamp between (datetime(2026-01-01) .. datetime(2026-01-02))

Null Handling

// Check for nulls
| where isnotnull(temperature)

// Coalesce nulls
| extend temp = coalesce(temperature, 0)

---

Query API Issues

API Returns 404

Cause: Query not found or endpoint incorrect

Fix:

1. Verify query name exactly matches
2. Check the workspace and surface
3. Ensure query is saved (not just drafted)

API Returns 401/403

Cause: Authentication or authorization issue

Fix:

1. Check API key is correct
2. Verify token hasn't expired
3. Ensure you have API access permissions

API Returns 500

Cause: Query execution error

Fix:

1. Test query in the UI first
2. Check KQL syntax
3. Verify data source is accessible

---

Working with Azi

Ask Azi to Build Queries

Good prompts:

• "Show me average temperature by hour for the last 24 hours"
• "Find all readings where pressure exceeded 100 PSI"
• "Count devices by location"

What Azi does:

1. Proposes KQL query
2. Explains what it does
3. Waits for your approval
4. You can edit, approve, or reject

Ask Azi to Debug Queries

Good prompts:

• "Why is this query returning empty?"
• "Help me fix this KQL error: [paste error]"
• "Optimize this query for better performance"

---

Query Best Practices

Structure for Success

// 1. Start with table
YourTable

// 2. Time filter first (most important!)
| where timestamp > ago(1h)

// 3. Row filters next
| where device_id == "sensor-001"
| where temperature > 70

// 4. Projections (select columns)
| project timestamp, device_id, temperature

// 5. Aggregations last
| summarize avg(temperature) by bin(timestamp, 5m)

Naming Queries

Good names:

• hourly-temperature-avg
• production-line-status
• quality-alerts-last-24h

Bad names:

• query1
• test
• new query

---

Error Reference

"Table not found"

Cause: Table name is incorrect or data hasn't arrived yet

Fix:

1. Check exact table name (case-sensitive)
2. Verify connection has sent data
3. Wait for data to be indexed

"Column not found"

Cause: Field name typo or field doesn't exist

Fix:

1. Run YourTable | take 1 | project * to see all fields
2. Check exact spelling
3. Check case sensitivity

"Query timeout"

Cause: Query scanning too much data

Fix:

1. Add time filter at start
2. Reduce time range
3. Add more specific filters

---

Ask Azi

In chat, try:

• "Debug this query: [paste KQL]"
• "Why does this return empty?"
• "Write a query to find [what you need]"

---

Related

• Query Returns Empty - Detailed empty results diagnosis
• Surfaces Troubleshooting - Surface configuration issues
• KQL Basics - Learn KQL fundamentals