Query fields, operators, and macros in Azure Boards and Azure DevOps
TFS 2017 | TFS 2015 | TFS 2013
Here you'll find detailed descriptions of each field data type, query operators, and query macros. Some data types, operators, and macros are only valid for the indicated Azure DevOps Server or Team Foundation Server (TFS) version.
For a quick reference of query tasks and operators and macros supported for each data type, see Query quick reference. See also Guidance to create high-performing queries for tips on constructing high-performing queries.
Query field data types and values
The value you specify for a field must conform to the data type for that field. The following table lists the supported data types:
Note
For Azure Boards cloud service, the data type corresponds to that listed for the field on the Process>Fields page. For on-premises deployments, the data type corresponds to the type attribute assigned to a FIELD definition. For more information, see Work item fields and field attributes.
Data type
Description
Boolean1
Specifies a field that takes on a True/False value.
DateTime or Date/Time
A date field in which you can specify a variable, such as @Today or @Today-1, or a value, such as 1/1/2012. Enter dates in the Date Pattern you set for your personal profile. (See Set personal preferences for details.) For query examples, see Query by date or@CurrentIteration.
For WIQL queries, you can also specify the date in the Coordinated Universal Time (UTC) pattern. For details, see Syntax for the Work Item Query Language (WIQL).
Double or Decimal
A real number, such as 0.2 or 3.5. For query examples, see Query by numeric fields.
GUID
A character string that represents a unique ID.
History
Custom formatted field used to track historical information. This data type is only used to support the History field. This field is automatically indexed for full-text search when full-text search is available. See Full-Text and partial word searches described later in this article. For query examples, see History and auditing.
HTML
Text strings that support formatted descriptions, such as the Description or Repro Steps fields. These fields are automatically indexed for full-text search when full-text search is available. See Full-Text and partial word searches described later in this article. To query rich-text fields, see Query by titles, IDs, and rich-text fields.
Identity
Short text string that identifies a user identity.
Integer
A 32-bit integer that is signed, such as 0, 1, 2, 34.
PlainText or Text field (multi-line)
Text strings that support long descriptions, such as the Application Start Information field. These fields are automatically indexed for full-text search, when full-text search is available. See Full-Text and partial word searches described later in this article. To query plain-text fields, see Query by titles, IDs, and rich-text fields.
picklistDouble2
Custom field defined to contain a pick list of Decimal values.
picklistInteger2
Custom field defined to contain a pick list of Integer values.
picklistString2
Custom field defined to contain a pick list of short text string (255 characters or less) values.
String or Text field (single line)
Short text string that can contain up to 255 Unicode characters. String text fields are often used to support picklists or drop-down menus.
TreePath
A branching tree structure, such as an Area Path or Iteration path. Choose an item from a list of valid values. Find work items that equal, not equal, under or not under a tree structure, or use the In or Not In operators to specify several values. You define the tree structure for a project—area paths and iteration paths—and then select the ones you want to associate with a team.
For more information on constructing queries, see Query by area or iteration path or Query by date or current iteration.
Note
- The Boolean data type field is supported for TFS 2017 and later versions.
- The picklist... data types are only assigned to custom fields defined for an inherited process. The Inherited process model is only supported for Azure DevOps Services and Azure DevOps Server 2019.
Query operators
You can use query operators in the following table to specify how each value in a clause must relate to the corresponding value in a work item. For information about the data type that is assigned to work item fields, see Work item field reference.
To learn about adding clauses and use of the And/Or operators, see Define a query, And/Or logical expression.
Query operator
Returns work items if the value in the work item matches the criteria listed
Applicable data types
=
Matches the value in the clause.
Number—which includes Double, GUID, Integer—and String, DateTime, and TreePath
<>
Doesn't match the value in the clause.
Number, String, DateTime, and TreePath
>
Is larger than the value in the clause.
Number, String, and DateTime
<
Is less than the value in the clause.
Number, String, and DateTime
>=
Is larger than or equal to the value in the clause.
Number, String, and DateTime
<=
Is less than or equal to the value in the clause.
Number, String, and DateTime
=[Field]
Matches the value that is contained in the specified field.
Name of a field that is of the same data type as the specified field
<>[Field]
Doesn't match the value that is contained in the specified field.
Name of a field that is of the same data type as the specified field
>[Field]
Is larger than the value that is contained in the specified field.
Name of a field that is of the same data type as the specified field
<[Field]
Is less than the value that is contained in the specified field.
Name of a field that is of the same data type as the specified field
>=[Field]
Is larger than or equal to the value that is contained in the specified field.
Name of a field that is of the same data type as the specified field
<=[Field]
Is less than or equal to the value that is contained in the specified field.
Name of a field that is of the same data type as the specified field
Contains
Contains an exact or partial match of the text string within the field you selected for filtering.
String
Does Not Contain
Doesn't contain an exact or partial match of the text string within the field you selected for filtering.
String
Contains Words
Contains the exact text string or words within the field you selected for filtering. You can also enter partial words or phrases that contain the wildcard character, *. Text string is limited to 100 characters. For restrictions, see Full-text searches for server and collation requirements.
Long-text fields that are indexed for full-text search, which correspond to all PlainText and HTML fields, and the History and Title fields.
Does Not Contain Words
Doesn't contain the exact text string or words within the field you selected for filtering. Text string is limited to 100 characters.
Use this operator in combination with a clause with the Contains Words operator to include and exclude specific keywords.
Text fields that are indexed for full text search.
In
Matches any value in a delimited set. For example, you can find work items whose IDs are 100, 101, and 102 if you specify those values for the ID field. Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma(,).
Number, String, DateTime, TreePath
Is Empty
Lists work items that contain an empty HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards (cloud service), Azure DevOps Server 2019, and later versions.
HTML
Is Not Empty
Lists work items that contain some content in the HTML field. You don't specify a value with this operator. This operator is supported for Azure Boards (cloud service), Azure DevOps Server 2019, and later versions.
HTML
Not In
Doesn't match any value in a delimited set. You can exclude work items whose states are not Resolved, Completed, or Closed from query results if you specify those values for the State field. Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma(,).
The Not In operator is available from Azure Boards and TFS 2018.2 and later versions.
Number, String, DateTime, TreePath
In Group
Matches a value that is a member of the group in the clause. Groups correspond to the name of a team, security group, or work tracking category. For example, you can create a query to find all work items that are assigned to members of the Contributors group or to a team. Team groups are created when you create a team. The name of team groups follows the pattern [Team Project Name]\Team Name.
For example queries, see Query by assignment or workflow changes.
String that matches the name of a team, security group, or category defined in the system.
Note
You can use the In Group operator only with fields that use the String data type or the Work Item Type field. You can also use groups defined in Azure Active Directory (Azure AD) when your Azure Boards account is backed by Azure AD, or Active Directory when your on-premises server instance is backed by Active Directory.
For information about category groups, see Use categories to group work item types.
Not in Group
Doesn't match a value that is a member of the group in the clause.
String that matches the name of a user group in Team Foundation Server or a category group defined for a project.
Note
You can use the Not In Group operator only with fields that use the String data type or the Work Item Type field. You can also use groups defined in Azure AD when your Azure Boards account is backed by Azure AD, or Active Directory when your on-premises server instance is backed by Active Directory.
Not Under
Doesn't match the value in the clause and isn't contained under the node in the clause.
TreePath
Under
Matches the value in the clause or is contained under the node in the clause.
TreePath
Was Ever
Matches the value in the clause at any previous point.
String , DateTime
Tip
It's possible to contruct a query using WIQL syntax that uses an operator, such as Was Ever, for other data type fields than those listed. For example, you can use Was Ever within a clause using the Iteration Path. For an example, see Query by date or current iteration, List work items moved out of a sprint.
Query macros or variables
You can use the macros described in the following table to filter your queries based on specific fields.
Note
The following macros are only supported from the web portal: @CurrentIteration, @CurrentIteration +/- n, @Follows, @MyRecentActivity, @RecentMentions, @RecentProjectActivity, and @TeamAreas. Queries that contain these macros won't work when opened in Visual Studio/Team Explorer, Microsoft Excel, or Microsoft Project.
Macro
Description
[Any]
Use with the Work Item Type or State fields to search across all work item types or across all states. For example, Work Item Type=[Any] won't place any filters based on the work item type.
@CurrentIteration
Use with the Iteration Path field to automatically filter for work items assigned to the current sprint based on the current team focus or context. For specific examples, see Query by date or current iteration.
The @CurrentIteration macro is supported for Azure Boards and TFS 2015 and later versions. This macro only works when run from the web portal. You can't use the macro when copying or cloning test suites and test cases, defining alerts, or with REST APIs.
@CurrentIteration +/- n
Use with the Iteration Path field to filter the set of work items assigned to the current sprint +/- n sprints based on the current team focus or context. For specific examples, see Query by date or current iteration.
The @CurrentIteration +/- n macro is supported for Azure Boards, Azure DevOps Server 2019 and later versions, and only when run from the web portal.
@Follows
Use with the ID field and In operator to list all work items that you are following in the project. To learn more about the Follow feature, see Follow a work item or pull request. You can view this same list from the Work Items page, Following pivot view.
The @Follows macro is supported for Azure Boards and TFS 2017 and later versions, and only when run from the web portal.
@Me
Use with an identity or user account field to automatically search for items associated with your user or account name. For example, you can find work items that you opened with the clause Created By=@Me. For more examples, see Query by assignment, workflow, or Kanban board changes.
@MyRecentActivity 1
Use with the ID field and In operator to list work items that you have viewed or updated in the project within the last 30 days. You can view this same list from the Work Items page, My activity pivot view.
@Project
Use with the Team Project field to filter for work items in other projects. For example, you can find all the work items in the currently selected project with the clause Team Project=@Project.
The @Project macro is supported for Azure Boards and TFS 2015.1 and later versions. The system automatically defaults to filtering based on the current project. To learn more, see Define a query, Query across projects.
@RecentMentions 1
Use with the ID field and In operator to list work items where you have been mentioned in the Discussion section. You can view this same list from the Work Items page, Mentioned pivot view.
@RecentProjectActivity
Use with the ID field and In operator to list work items that have been updated in the project within the last 30 days. You can view similar lists from the Work Items page, Recently created, Recently updated and Recently completed pivot views.
The @RecentProjectActivity macro is supported for Azure Boards (cloud service) only at this time.
@StartOfDay 2
Use with a DateTime field to filter for work items that relate to the current date or with a plus/minus offset. For example, you can find all items closed in the last week with the clause Closed Date>=@StartOfDay-7. For more examples, see Query by date or current iteration.
@StartOfMonth 2
Use with a DateTime field to filter for work items that relate to the current month or with a plus/minus offset. For example, you can find all items created in the last three months with the clause Created Date>=@StartOfMonth-3. For more examples, see Query by date or current iteration.
@StartOfWeek 2
Use with a DateTime field to filter for work items that relate to the current week or with a plus/minus offset. For example, you can find all items changed in the last two weeks with the clause Changed Date>=@StartOfWeek-2. For more examples, see Query by date or current iteration.
@StartOfYear 2
Use with a DateTime field to filter for work items that relate to the current year or with a plus/minus offset. For example, you can find all features that have a Target Date scheduled within the current year with the clause Target Date>=@StartOfYear. For more examples, see Query by date or current iteration.
@TeamAreas
Only use with the Area Path field to filter for work items whose area path corresponds to one assigned to a specific team. Requires you use the = operator. For example, you can find all items assigned to the area paths assigned to the Web team with the clause Area Path=@TeamAreas [Fabrikam Fiber]\Web. For more examples, see Query by area or iteration path.
The @TeamAreas macro is supported for Azure DevOps Server 2019 and later versions, and only when run from the web portal.
@Today
Use with a DateTime field to filter for work items that relate to the current date or to an earlier date. You can also modify the @Today macro by subtracting days. For example, you can find all items created in the last week with the clause Created Date>=Today-7. For more examples, see Query by date or current iteration.
Note
- The @MyRecentActivity, @RecentMentions, and @RecentProjectActivity macros are supported for Azure Boards and TFS 2018.2 and later versions.
- The @StartOfDay, @StartOfWeek, @StartOfMonth, and @StartOfYear macros are supported for Azure DevOps Server 2019 Update 1 and later versions.
Full-text and partial word searches
Specify Contains or Does Not Contain to search against exact or partial matches of a word or phrase. These operators filter items based on the full-text search index created for long-text fields. Specify Contains Words or Does Not Contain Words to search against an exact phrase or to use the wildcard character, *. These operators use the full-text search index. You can only use the wildcard character at the end of a partial word or phrase.
For examples, see Example work item queries and Query for work items using the History field.
Note
Not all deployments support full-text searches. For example, SQL Express and SQL Azure, which support the cloud service, do not support full-text search. In these instances, you will only see the Contains and Does not Contain operators.
Azure DevOps Server and Team Foundation Server automatically index all long-text fields with a data type of PlainText and HTML and the Title field for full-text search. The index and operators are only available when the SQL Server that supports Team Foundation Server supports full-text search.
Full-text searches require a SQL collation that corresponds to a language that has a word breaker registered with SQL Server. If the collation settings for the project collection database used for your Team Foundation Server instance don't correspond to a supported language, your search results may not match your expectations. In these cases, you might try using the Contains or Does Not Contain operators.
For more information, see Full-Text Search Queries and Collation Settings.
Related articles
- Query quick reference
- About managed queries
- Work item field index
- Syntax for the Work Item Query Language (WIQL)
SDK resources
To programmatically interact with queries, see Query for Bugs, Tasks, and Other Work Items.