| title | titleSuffix | description | ms.custom | ms.technology | ms.assetid | ms.author | author | ms.topic | monikerRange | ms.date |
|---|---|---|---|---|---|---|---|---|---|---|
Query fields, operators, and macros/variables |
Azure Boards |
Field data types, operators, and macros/variables used by the Query Editor in Azure Boards, Azure DevOps, & Team Foundation Server |
boards-queries |
devops-agile |
814c2dca-cf8f-44bf-bba1-a5d8e293fc05 |
kaelli |
KathrynEE |
reference |
>= tfs-2013 |
02/04/2019 |
[!INCLUDE temp]
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.
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 |
A date field in which you can specify a variable, such as or , 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 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 |
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. You can choose an item from a list of valid values. You can 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. |
- 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.
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.
| 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 |
<> |
Does not 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] |
Does not 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 |
Does not 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, *. 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 |
Does not contain the exact text string or words within the field you selected for filtering. |
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 |
Does not match any value in a delimited set. For example, 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 (AAD) when your Azure Boards account is backed by AAD, or Active Directory (AD) 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 |
Does not 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 AAD when your Azure Boards account is backed by AAD, or AD when your on-premises server instance is backed by AD. |
Not Under |
Does not match the value in the clause and is not 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 |
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, @Follows, @MyRecentActivity, @RecentMentions, @RecentProjectActivity, @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 in conjunction with the Work Item Type field to search across all work item types. For example, Work Item Type=[Any] won't place any filters based on the work item type.
|
| 1 | Use in conjunction 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.
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. |
| +/- n 2 | Use in conjunction 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. |
| 3 | Use in conjunction 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. |
Use in conjunction 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=. For additional examples, see Query by assignment, workflow or Kanban board changes.
|
|
| 4 | Use in conjunction 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. |
| 5 | Use in conjunction with the Team Project field to filter for work items in the current project. For example, you can find all the work items in the current project with the clause Team Project=.
|
| 4 | Use in conjunction 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. |
| 6 | Use in conjunction 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. |
| 7 | 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>=. For additional examples, see Query by date or current iteration. |
| 7 | 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 3 months with the clause Created Date>=. For additional examples, see Query by date or current iteration. |
| 7 | 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>=. For additional examples, see Query by date or current iteration. |
| 7 | 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>=. For additional examples, see Query by date or current iteration. |
| 8 | 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= [Fabrikam Fiber]\Web. For additional examples, see Query by area or iteration path. |
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 macro by subtracting days. For example, you can find all items created in the last week with the clause Created Date>=. For additional examples, see Query by date or current iteration. |
- The macro is supported for Azure Boards and TFS 2015 and later versions.
- The +/- n macro is supported for Azure Boards, Azure DevOps Server 2019 and later versions, and only when run from the web portal.
- The macro is supported for Azure Boards and TFS 2017 and later versions.
- The , , macros are supported for Azure Boards and TFS 2018.2 and later versions.
- The 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 Query across projects.
- The macro is supported for Azure Boards (cloud service) only at this time.
- The , , , and macros are supported for Azure DevOps Server 2019 Update 1 and later versions.
- The macro is supported for Azure Boards and Azure DevOps Server 2019 and later versions.
Specify Contains or Does Not Contain to search against exact or partial matches of a word or phrase. 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.
Contains Words and Does Not Contain Words filter items based on the full-text search index created for long-text fields.
::: moniker range=">= tfs-2013 <= azure-devops-2019" Azure DevOps Server and Team Foundation Server automatically indexes 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 which has a word breaker registered with SQL Server. If the collation settings for the project collection database used for your Team Foundation Server instance do not 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.
::: moniker-end
- Query quick reference
- About managed queries
- Work item field index
- Syntax for the Work Item Query Language (WIQL)
[!INCLUDE temp]