Work Item Query Language (WIQL) syntax reference

TFS 2017 | TFS 2015 | TFS 2013

You can use the WIQL syntax to define a query as a hyperlink or when using the Work Item Query Language (REST API).

A query defined using the Work Item Query Language (WIQL) consists of a SELECT statement that lists the fields to be returned as columns in the result set. You can further qualify the result set by using a logical expression. You can specify a sort order. Use an ASOF clause to state that a query was evaluated previously.

Prerequisites

A query returns only those work items for which you have the View work items or View work items in this node permission. Typically, these permissions are granted to members of the Readers and Contributors groups for each team project. For more information, see Permissions and groups.

Query language overview

The work item query language has five parts shown in the following syntax snippet and described in the following table.

SELECT [State], [Title] 
FROM WorkItems
WHERE [Work Item Type] = 'User Story'
ORDER BY [State] Asc, [Changed Date] Desc
ASOF '6/15/2010'

The WIQL syntax isn't case-sensitive.

Limits on WIQL length

The WIQL length of queries made against Azure Boards must not exceed 32K characters. The system won't allow you to create or run queries that exceed that length.

WHERE filter conditions

The WHERE clause specifies the filter criteria. The query returns only work items that satisfy the specified criteria. For example, the following example WHERE clause returns user stories that are active and that are assigned to you.

WHERE [Work Item Type] = 'User Story'
AND [State] = 'Active'
AND [Assigned to] = @Me

You can control the order in which logical operators are evaluated by enclosing them within parentheses to group the filter criteria. For example, to return work items that are either assigned to you or that you closed, change the query filter to match the following example.

WHERE [Work Item Type] = 'User Story'
AND [State] = 'Active'
AND ( [Assigned to] = @Me
OR [Closed by] = @Me )

Filter conditions

Each filter condition is composed of three parts, each of which must conform to the following rules:

• Field: You can specify either the reference name or friendly name. The following examples are valid WIQL syntax:
  • Reference name with spaces: SELECT [System.AssignedTo] ...
  • Friendly name with spaces: SELECT [Assigned To] ...
  • Names without spaces don't require square brackets: SELECT ID, Title ...
• Comparison operator: Valid values are specified in the Operators section later in this article. -
• Field value: You can specify one of the following three values depending on the field specified.
  • A literal value must match the data type of the field value.
  • A *variable or macro that indicates a certain value. For example, @Me indicates the person who is running the query. For more information, see Macros and variables later in this article.
  • The name of another field. For example, you can use [Assigned to] = [Changed by] to find work items that are assigned to the person who changed the work item most recently.

For a description and reference names of all system-defined fields, see Work item field index.

Operators

Queries use logical expressions to qualify result sets. These logical expressions are formed by one or more conjoined operations.

Some simple query operations are listed below.

WHERE [System.AssignedTo] = 'joselugo'  
WHERE [Adatum.CustomMethodology.Severity] >= 2

The table below summarizes all the supported operators for different field types. For more information on each field type, see Work item fields and attributes.

The =, <>, >, <, >=, and <= operators work as expected. For instance, System.ID > 100 queries for all work items with an ID greater than 100. System.ChangedDate > '1/1/19 12:00:00' queries for all work items changed after noon of January 1, 2019.

Beyond these basic operators, there are some behaviors and operators specific to certain field types.

Logical groupings

You can use the terms AND and OR in the typical Boolean sense to evaluate two clauses. You can use the terms AND EVER and OR EVER when specifying a WAS EVER operator. You can group logical expressions and further conjoin them, as needed. Examples are shown below.

WHERE [System.State] =  'Active' 
    AND [System.AssignedTo] = 'joselugo' 
	AND ([System.CreatedBy] = 'linaabola' 
    OR [Adatum.CustomMethodology.ResolvedBy] = 'jeffhay') 
    AND [System.State] = 'Closed'
    WHERE [System.State] = 'Active'
    AND [System.State] EVER 'Closed'

You can negate the contains, under, and in operators by using not. You can't negate the ever operator. The examples below query for all work items that aren't classified within the subtree of 'MyProject\Feature1'.

WHERE [System.AreaPath] not under 'MyProject\Feature1'
WHERE [System.AssignedTo] ever 'joselugo'

Example query, Was Ever Assigned To

The WIQL syntax is shown next for the following query constructed through the Query Editor. This example finds all work items that were ever assigned to Jamal Hartnett.

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State],
    [System.Tags]
FROM workitems
WHERE
    [System.WorkItemType] <> ''
    AND (
        [System.State] <> ''
        OR EVER [System.AssignedTo] = 'Jamal Hartnett <[email protected]>'
    )
ORDER BY [System.Id]

Macros or variables

The following table lists the macros or variables you can use within a WIQL query.

@me macro

The @me macro replaces the Windows Integrated account name of the user who runs the query. The example below shows how to use the macro and the equivalent static statement. Although the macro is intended for fields such as Assigned To, you can use it for any String field, although the result may not be meaningful.

[System.AssignedTo] = @Me
[System.AssignedTo] = 'joselugo'

@today macro

You can use the @today macro with any DateTime field. This macro replaces midnight of the current date on the local computer that runs the query. You can also specify @today+x or @today-y using integer offsets for x days after @today and y days before @today, respectively. A query that uses the @today macro can return different result sets depending on the time zone in which it's run.

The examples below assumes that today is 1/3/19.

[System.CreatedDate] = @today

Is the equivalent of:

[System.CreatedDate] = '1/3/19'

And

[System.CreatedDate] > @today-2

Is the equivalent of:

[System.CreatedDate] > '1/1/19'

Custom macros

WIQL also supports arbitrary custom macros. Any string prefixed by an '@' is treated as a custom macro and will be substituted. The replacement value for the custom macro is retrieved from the context parameter of the query method in the object model. The following method is the API used for macros:

public WorkItemCollection Query(string wiql, IDictionary context)

The context parameter contains key-value pairs for macros. For example, if the context contains a key-value pair of (project, MyProject), then '@project' will be replaced by 'MyProject' in the WIQL. This replacement is how the work item query builder handles the @project macro in Visual Studio.

ASOF historical queries

You can use an ASOF clause in a query to filter for work items that satisfy the specified filter conditions as they were defined on a specific date and time.

Suppose a work item was classified under an iteration path of MyProject\ProjArea and assigned to 'Mark Hanson' on 3/17/16. However, the work item was recently assigned to 'Roger Harui' and moved to a new iteration path of Release. The following example query will return this work item because the query is based on the state of work items as of a past date and time.

SELECT [System.Title] 
    FROM workitems 
    WHERE ([System.IterationPath] = 'MyProject\ProjArea' and [System.AssignedTo] = 'Mark Hanson') 
    ASOF '3/16/16 12:30'

ORDER BY clause to sort results

You can use the ORDER BY clause to sort the results of a query by one or more fields in ascending or descending order.

The following example sorts work items first by Priority in ascending order, and then by Created Date in descending order.

SELECT [System.Title] 
    FROM workitems 
    WHERE [System.State] =  'Active' and [System.AssignedTo] =  'joselugo' 
    ORDER BY [Microsoft.VSTS.Common.Priority] asc, [System.CreatedDate] desc

Query for links between work items

To return links between work items, you specify FROM WorkItemLinks. Filter conditions in the WHERE clause may apply to the links or to any work item that is the source or the target of a link. For example, the following query returns the links between user stories and their active child nodes.

SELECT [System.Id]
FROM WorkItemLinks
WHERE ([Source].[System.WorkItemType] = 'User Story')
  AND ([System.Links.LinkType] = 'Child')
  AND ([Target].[System.State] = 'Active')
MODE (MustContain)

The following table summarizes the differences between work item queries and queries for links between work items.

You can specify one of the system link type names, listed below, or a custom link type you've defined with the On-premises XML process.

• System.LinkTypes.Hierarchy-Forward
• System.LinkTypes.Related
• System.LinkTypes.Dependency-Predecessor
• System.LinkTypes.Dependency-Successor
• Microsoft.VSTS.Common.Affects-Forward (CMMI process)

For more information, see Link type reference.

Tree type query example

The following query returns all work item types define in the current project. The query as shown in the Query Editor appears as shown in the following image.

The equivalent WIQL syntax is shown below.

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State],
    [System.Tags]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
    )
MODE (Recursive)

Direct-link query example

The following query returns all work item types define in the current project. The query as shown in the Query Editor appears as shown in the following image.

The equivalent WIQL syntax is as shown.

SELECT
    [System.Id],
    [System.WorkItemType],
    [System.Title],
    [System.AssignedTo],
    [System.State],
    [System.Tags]
FROM workitemLinks
WHERE
    (
        [Source].[System.TeamProject] = @project
        AND [Source].[System.WorkItemType] <> ''
        AND [Source].[System.State] <> ''
    )
    AND (
        [System.Links.LinkType] = 'System.LinkTypes.Dependency-Reverse'
        OR [System.Links.LinkType] = 'System.LinkTypes.Related-Forward'
        OR [System.Links.LinkType] = 'System.LinkTypes.Dependency-Forward'
    )
    AND (
        [Target].[System.TeamProject] = @project
        AND [Target].[System.WorkItemType] <> ''
        AND [Target].[System.ChangedDate] >= @today - 60
    )
ORDER BY [System.Id]
MODE (MustContain)

More query examples

The following typical WIQL query example uses reference names for the fields. The query selects work items (no work item type specified) with a Priority=1. The query returns the ID and Title of the return set as columns. The results are sorted by ID in ascending order.

SELECT System.ID, System.Title 
FROM workitems 
WHERE Priority=1 
ORDER BY System.ID asc

Date-time pattern

You specify the date-time pattern according to one of two patterns:

• The Date Pattern and Time Pattern format comes from your browser's language/region selection.
• The pattern specified by UTC, which follows this pattern (with Z appended to the date-time):

AND System.ChangedDate >= '1/1/2019 00:00:00Z'

Example clauses

The following example statements show specific qualifying clauses.

SELECT [System.Id], [System.Title]
FROM WorkItems
WHERE [System.TeamProject] = @project
AND [System.AssignedTo] = 'Judy Lew'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND ( [System.AssignedTo] = 'Mark Steele'
OR [System.AssignedTo] = 'Merav Sror' )

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Anne Wallace'
AND [System.AssignedTo] NOT CONTAINS 'Danny Levin'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'Anne Wallace'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] EVER 'David Galvin'
AND [System.AreaPath] UNDER 'Agile1\Area 0'

SELECT [System.Id], [System.Title] 
FROM WorkItems 
WHERE [System.TeamProject] = @project 
AND [System.AssignedTo] = 'Jon Ganio'
ORDER BY [System.Id] [asc | desc]

SELECT [System.Title] 
FROM workitems 
WHERE [System.IterationPath] = 'MyProject\Beta' 
AND [System.AssignedTo] = 'Jim Daly' 
ASOF '3/16/19 12:30'

DateTime

Quote (single or double quotes are supported) DateTime literals used in comparisons. They must be in the .NET DateTime format of the local client computer running the query. Unless a time zone is specified, DateTime literals are in the time zone of the local computer.

WHERE [Adatum.Lite.ResolvedDate] >= '1/8/19 GMT' and [Resolved Date/Time] < '1/9/19 GMT'
WHERE [Resolved Date] >= '1/8/19 14:30:01'

When the time is omitted in a DateTime literal and the dayPrecision parameter equals false, the time is assumed to be zero (midnight). The default setting for the dayPrecision parameter is false.

String and PlainText

Quote string literals (single or double quotes are supported) in a comparison with a string or plain text field. String literals support all Unicode characters.

WHERE [Adatum.Lite.Blocking] = 'Not Blocking'
WHERE [Adatum.Lite.Blocking] <> 'Blocked'

You can use the contains operator to search for a substring anywhere in the field value.

WHERE [System.Description] contains 'WIQL' 

Area and Iteration (TreePath)

You can use the UNDER operator for the Area and Iteration Path fields. The UNDER operator evaluates whether a value is within the subtree of a specific classification node. For instance, the expression below would evaluate to true if the Area Path were 'MyProject\Server\Administration', 'MyProject\Server\Administration\Feature 1', 'MyProject\Server\Administration\Feature 2\SubFeature 5', or any other node within the subtree.

WHERE [System.AreaPath] UNDER 'MyProject\Server\Administration'

Modifiers and special operators

You can use some modifiers and special operators in a query expression.

Use the IN operator to evaluate whether a field value is equal to any of a set of values. This operator is supported for the String, Integer, Double, and DateTime field types. See the following example along with its semantic equivalent.

WHERE [System.CreatedBy] IN ('joselugo', 'jeffhay', 'linaabola')
WHERE [System.CreatedBy] = 'joselugo' OR [System.CreatedBy] = 'jeffhay' OR [System.CreatedBy] = 'linaabola'

The EVER operator is used to evaluate whether a field value equals or has ever equaled a particular value throughout all past revisions of work items. The String, Integer, Double, and DateTime field types support this operator. There are alternate syntaxes for the EVER operator. For example, the snippets below query whether all work items were ever assigned to 'joselugo'.

WHERE EVER ([Assigned To] =  'joselugo')
WHERE [Assigned To] EVER 'joselugo'

Related articles

• Query fields, operators, values, and variables
• Work item fields and attributes
• About managed queries
• Cross-service and enhanced query operations
• Define a query