wiql-queries

# WIQL Query Reference (Verified)

## CRITICAL LIMITATIONS - READ FIRST

1. **NO TOP CLAUSE** - WIQL does NOT support `SELECT TOP N` like SQL Server. Limit results with shell:
   ```bash
   az boards query --wiql "..." -o table | head -10
   ```

2. **Use explicit project name** - The `@project` macro is unreliable in CLI:
   ```sql
   -- UNRELIABLE:
   WHERE [System.TeamProject] = @project

   -- RELIABLE:
   WHERE [System.TeamProject] = 'YourProjectName'
   ```

3. **Only flat queries supported** - The CLI only supports flat queries, not tree/hierarchical queries.

4. **NO LIKE OPERATOR** - WIQL does NOT support SQL-style LIKE patterns. Use CONTAINS instead:
   ```sql
   -- DOES NOT WORK:
   WHERE [System.Title] LIKE '%keyword%'

   -- USE THIS INSTEAD:
   WHERE [System.Title] CONTAINS 'keyword'
   ```

5. **CANNOT ORDER BY System.Parent** - Sorting by parent ID is not supported:
   ```sql
   -- DOES NOT WORK:
   ORDER BY [System.Parent]

   -- WORKAROUND: Filter by parent IDs with IN clause, sort client-side
   WHERE [System.Parent] IN (1234, 1235, 1236) ORDER BY [System.Id]
   ```

## Basic Query Syntax

```bash
az boards query --wiql "SELECT [fields] FROM workitems WHERE [conditions]" -o table
```

## Verified Working Examples

### Query all work items in project
```bash
az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM workitems WHERE [System.TeamProject] = 'ProjectName'" -o table
```

### Query by state
```bash
az boards query --wiql "SELECT [System.Id], [System.Title] FROM workitems WHERE [System.State] = 'In Progress' AND [System.TeamProject] = 'ProjectName'" -o table
```

### Query by work item type
```bash
az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM workitems WHERE [System.WorkItemType] = 'Bug' AND [System.TeamProject] = 'ProjectName'" -o table
```

### Query by assignee
```bash
az boards query --wiql "SELECT [System.Id], [System.Title] FROM workitems WHERE [System.AssignedTo] = 'user@domai