Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
When you want to find work items based on a keyword or phrase or a null text field, you can do so by filtering on single-line text (String), multi-line text (PlainText), and rich-text (HTML) fields. If you find that your queries take too long to return results, see Create a query, Best practices.
Category | Requirements |
---|---|
Access levels | - To view and run shared queries: Project member. - To add and save a shared query: At least Basic access. |
Permissions | Contribute permission set to Allow for the folder that you want to add a query to. By default, the Contributors group doesn't have this permission. |
Note
Users with Stakeholder access for a public project have full access to query features just like users with Basic access. For more information, see Stakeholder access quick reference.
Category | Requirements |
---|---|
Access levels | - To view and run shared queries: Project member. - To add and save a shared query: At least Basic access. |
Permissions | Contribute permission set to Allow for the folder that you want to add a query to. By default, the Contributors group doesn't have this permission. |
Query clauses that specify a text or rich-text field can use the operators and macros listed in the following table.
Data type
Supported operators and macros
Rich-text (HTML)
Multi-line text strings (PlainText)
Contains Words
, Does Not Contain Words
, Is Empty
1, Is Not Empty
1
Single text (String)
= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Does Not Contain, In, Not In, In Group, Not In Group, Was Ever
Macros: [Any]
, valid with the Work Item Type field and @Project
2, valid with the Team Project field.
ID
= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever
Macros: @Follows
, @MyRecentActivity
, @RecentMentions
, @RecentProjectActivity
valid with the ID field and In
and Not In
operators
@Project
2, valid with the Team Project field.
State and Work Item Type fields
= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field],
Contains,
Does Not Contain,
In,
Not In,
In Group,
Not In Group,
Was Ever **Macros**:
[Any]` valid with both fields.
Note
Is Empty
and Is Not Empty
operators are supported for Azure DevOps Server 2019 RC2 and later versionsWhen you want to filter on a string match, try using the Contains Words
operator instead of Contains
. The Contains Words
operator runs a full-text search on the specified field, which is faster in most cases. Text string is limited to 100 characters.
While the Contains
operator runs a table scan, which isn't only slower, but also consumes more CPU cycles. These CPU cycles contribute towards your resource consuming rate limit.
Note
The Contains Words
operator makes use of SQL's full-text search indexing. When a new value is saved to a long-text field, SQL Server will:
When a user then runs a query on this field using the Contains Words
operator, the search will be run against the unique keywords stored in the index. For long-text fields, this makes searching much more efficient and quicker than doing a substring search. By default, SQL defines a "word" as a set of characters between punctuation. For example, periods signify the end of a word, but the period is not considered to be part of the word. Because the full-text search index contains keywords instead of exact phrases, you'll end up getting all the results that contain the same keywords, as determined by the indexing.
Use Contains or Contains Words to list items that partially or exactly match the words or phrase that you enter.
Choose Contains or Does Not Contain to search against exact or partial matches of a word or phrase. Choose 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.
For example, specify Contains Words and inform* to filter on a text field that contains inform or information or informational.
Tip
To understand how AND/OR
clauses are grouped, see Create and save managed queries, Group clauses. To view the WIQL syntax for a query, install the WIQL query editor extension which allows you to see the WIQL version of any query editor entry.
Use Contains Words and Does Not Contain Words operators to list items that exactly match the words or phrase that you enter, and exclude other words or phrases. You can use these operators in combination and with the wildcard character (*).
In the following example, these operators filter work items for those items that contain the work Phase but not the word Phasor.
Note
Certain reserved words in SQL, such as WHERE
, THEN
, and AND
, do not return results when used as standalone search terms with the Contains Words
or Does Not Contain Words
filters.
You can find work items that have an undefined field value by using the equals operator =
and leaving the Value for the field blank. For example, the following filters list all work items of type Task whose Activity field is blank.
To list work items based on a field that isn't blank, use the not operator <>
and leave the Value blank.
You can find work items with empty Descriptions. Using the Is Empty or Is Not Empty with an HTML field supports listing work items with empty or not empty rich text fields. You don't specify a value with this operator.
For example, the following query filters list all work items with some Description field entries.
To filter for a URL or a phrase that contains special characters like /
or -
, use a backslash to escape these characters. The following examples show how to filter for a URL and for a phrase with a dash:
Filter for a URL: Search for a work item title that includes the phrase https://example.com/path-to-resource
.
Title ~ "https:\/\/example.com\/path-to-resource"
Filter for a phrase with a dash: Search for a work item title that includes "your-phrase-with-dash"
.
Title ~ "feature-update\-2023"
Note
You can't query for work items that don't have any tags attached to them. To up vote this feature request, do so on our Developer Community page, Be able to search for empty tags.
To filter work items based on the category they belong to, use the In Group operator. For example, the following filter criteria return all work items that are in the current project, assigned to the team member, and defined as belonging to the Bug Category.
The default assignments of work item types to each category are listed as follows for each process.
Process | Requirement category | Task category |
---|---|---|
Basic | Issue | Task |
Agile | User Story | Task |
Scrum | Product Backlog Item, Bug | Task |
CMMI | Requirement | Task |
Each team can determine if the Bug work item type appears in either the Requirement or Task category. See Show bugs on backlogs and boards. You can add custom work item types to a backlog. For more information, see Add or modify a work item type, Add a custom WIT to a backlog or board.
You can use the @Follows macro to filter a list based on work items you're following along with other query filters.
For example, the following query shows how to query across all projects for active work items that you're following. You use the ID field and the In operator with the @Follows macro.
You can use the following macros to list work items based on recent activity:
Specify the ID field and either the In or Not In operators.
For example, the following query shows how to query for work items that you recently viewed or modified.
The following table describes common fields used to filter queries. The ID fields uniquely identify work items in a list. Use the Title field to distinguish the work item from all others of the same type. The Description and other rich-text (data type=HTML) fields provide additional information that is needed to implement work and track changes. After a work item is created, you can modify all fields except for the ID. When you add and save a work item, the ID gets assigned by the system and can't be changed.
Note
The system automatically indexes all long-text fields with a data type of PlainText and HTML fields for full-text search. This includes the Title, Description, and Steps to Repro fields. For more information and server and collation requirements applicable to on-premises Azure DevOps, see Query fields, operators, values, and variables - Full-text and partial word searches.
Field name
Description
Work item type
Acceptance Criteria 1
A description of the criteria to be met before the bug or product backlog item can be closed.
Before work begins on a bug or product backlog item, the criteria for customer acceptance should be described as clearly as possible. Conversations between the team and customers to define the acceptance criteria helps ensure that your team understands your customers' expectations. The acceptance criteria can be used as the basis for acceptance tests so that you can more effectively evaluate whether an item is satisfactorily completed.
Reference name=Microsoft.VSTS.Common.AcceptanceCriteria, Data type=HTML
Bug, Epic, Feature, Product backlog item (Scrum)
Description 1, 2
Use this field to provide in-depth information about a work item.
Reference name=System.Description, Data type=HTML
All
ID
The unique identifier that is assigned to a work item. Work item IDs are unique across all projects and within a project collection.
Reference name=System.Id, Data type=Integer
All
Repro Steps (or Steps to reproduce) 1
The steps that are required to reproduce unexpected behavior. Capture enough information so that other team members can understand the full effect of the problem and whether they fixed the bug. This entry includes actions taken to find or reproduce the bug and expected behavior.
Reference name=Microsoft.VSTS.TCM.ReproSteps, Data type=HTML
Bug
Resolution
Describes how an impediment was resolved.
Reference name=Microsoft.VSTS.Common.Resolution, Data type=HTML
Impediment (Scrum)
System Info1
Information about the software and system configuration that is relevant to the bug, code review, or feedback.
Reference name=Microsoft.VSTS.TCM.SystemInfo, Data type=HTML
Bug, Code Review Request, Feedback Request
Team Project
The project to which a work item belongs. Add this field to a query when you want to filter your list to items in one or more projects. For more information, see Example queries, query across projects.
Reference name=System.TeamProject, Data type=String
All
Title
A short description that summarizes what the work item is and helps team members distinguish it from other work items in a list.
Reference name=System.Title, Data type=String
All
Work Item Type
The name of the work item type. Work item types are defined based on the process used when you created your project. For more information, see About processes and process templates and Add or modify a work item type.
To filter work items based on their category assignment, you can use the In Group and Not In Group operators and select a category from the drop-down list.
Reference name=System.WorkItemType, Data type=String
All
Note
Upon upgrade to Team Foundation Server 2012, the Description field was changed from a field type of PlainText to HTML. Using the witadmin changefield command you can revert the data type for this field. See Manage work item fields (witadmin).
To programmatically interact with queries, see one of these REST API resources:
Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Learning path
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
Documentation
Query work items by link or attachment count in Azure Boards - Azure Boards
Learn how to query work items based on link type, link count, link restrictions, and attached file count in Azure Boards.
Query by account, user, workflow, or board changes in Azure Boards - Azure Boards
Learn how to list work items based on changes made to their assignment, state, or board column or swimlane in Azure Boards.
Query by area or iteration path in Azure Boards and Azure DevOps - Azure Boards
Learn how to query for work items based on their area or iteration path in Azure Boards and Azure DevOps.