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:

   az boards query --wiql "..." -o table | head -10
   

2. Use explicit project name - The @project macro is unreliable in CLI:

   -- 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:

   -- 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:

   -- 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

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

Verified Working Examples

Query all work items in project

az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM workitems WHERE [System.TeamProject] = 'ProjectName'" -o table

Query by state

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

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

az boards query --wiql "SELECT [System.Id], [System.Title] FROM workitems WHERE [System.AssignedTo] = '[email protected]' AND [System.TeamProject] = 'ProjectName'" -o table