Edit

Share via

Query by titles, IDs, and rich-text fields

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Filter work items by keywords, IDs, or empty text fields by using single-line text (String), multi-line text (PlainText), and rich-text (HTML) fields. If queries take too long to return, see Create a query, Best practices.

Prerequisites

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.

Supported operators and macros

Use the operators and macros listed for text and rich-text fields.

Data type

Supported operators and macros

Rich-text (HTML)
Multi-line text strings (PlainText)

Contains Words, Does Not Contain Words, Is Empty1, Is Not Empty1

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 @Project2, 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.
@Project2, 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

  1. The Is Empty and Is Not Empty operators are supported for Azure DevOps Server 2020 and later versions.
  2. The system defaults to filtering based on the current project. For more information, see Query across projects.

Use Contains Words for string matches

When you want to filter on a string match, prefer the Contains Words operator over Contains. Contains Words uses the full-text index and is typically faster. Text strings are limited to 100 characters.

The Contains operator runs a table scan; it's slower and consumes more CPU resources, which can affect your rate limits.

Note

The Contains Words operator uses SQL full-text search indexing. When a new value is saved to a long-text field, SQL Server:

  • Splits the phrase into words
  • Removes common stop words (for example, "a" or "is")
  • Converts words to their common stem (for example, running → run)
  • Stores the resulting keywords in an index

Queries that use Contains Words search the index, giving faster results for long-text fields. For more information and server/collation requirements, see Query fields, operators, values, and variables - Full-text and partial word searches.

Keyword or phrase query with wildcards

Use Contains or Contains Words to find items that partially or exactly match words or phrases.

Screenshot that shows the editor for a flat-list query used to filter keywords.

Choose Contains or Does Not Contain to search exact or partial matches. Choose Contains Words or Does Not Contain Words to use the full-text index and wildcard character *.

For example, Contains Words with inform* matches inform, information, and informational.

Screenshot that shows using a wildcard with the Contains Words operator.

Tip

To understand how AND/OR clauses are grouped, see 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.

Query for specific words and not others

Use Contains Words and Does Not Contain Words to include exact words or phrases and exclude others. Combine these operators and use * for wildcard matching.

The following example shows a filter that includes the work "Phase" but excludes "Phasor."

Screenshot that shows the Query Editor including and excluding exact words.

Note

Certain reserved SQL words, such as WHERE, THEN, and AND, don't return results when used as standalone search terms with Contains Words or Does Not Contain Words.

Undefined field value queries

Find work items with an undefined (blank) field value by using the "equals" operator = and leaving the Value blank. For example, the following filters list all tasks whose Activity field is blank.

Screenshot that shows a filter where the Activity value is blank.

To find items where a field isn't blank, use the "not" operator <> and leave the Value blank.

Empty or not empty HTML field queries

Use Is Empty or Is Not Empty with an HTML field to list work items with empty or nonempty rich-text fields. You don't specify a value for these operators.

Screenshot that shows filtering by non-empty HTML fields.

Filter for special characters

Escape special characters like / or - with a backslash when filtering URLs or phrases.

  • Filter for a URL:

    • Query: Title ~ "https:\/path-to-resource"
    • Results: Returns work items with the exact URL.

  • Filter for a phrase with a dash:

    • Query: Title ~ "feature-update\-2023"
    • Results: Returns work items that contain the exact phrase with dashes.

Note

You can't query for work items that don't have any tags attached. To upvote this feature request, visit Developer Community: Be able to search for empty tags.

Category-based queries

To filter by category, use the In Group operator. The example below returns items in the current project assigned to the team member and in the Bug category.

Screenshot that shows a clause that finds work items by category.

What items appear in the Requirement or Task categories?

Default work item type assignments for each process:

Process Requirement category Task category
Basic Issue Task
Agile User Story Task
Scrum Product Backlog Item, Bug Task
CMMI Requirement Task

Teams can choose whether the Bug work item type appears in the Requirement or Task category. See Show bugs on backlogs and boards. To add custom work item types to a backlog, see Add or modify a work item type.

Query for work items that you're following

Use the @Follows macro with the ID field and the In operator to list work items you follow, across projects if needed.

Screenshot that shows the Query Editor with ID In @Follows query clause

Query for recent work item activity

Use these macros to list items based on recent activity:

  • @MyRecentActivity: Items you recently viewed or modified.
  • @RecentMentions: Items with an @mention for you in the last 30 days.
  • @RecentProjectActivity: Items recently created or modified in your project.

Use the ID field with In or Not In.

Screenshot that shows the Query Editor with ID In @MyRecentActivity macro query

Common fields for most work item types

This table describes common fields used in queries. The ID uniquely identifies a work item. Use Title to distinguish items of the same type. Description and other rich-text fields provide detailed implementation info. After creation, you can modify all fields except ID; the system assigns the ID when the work item is created.

Note

The system indexes long-text fields of type PlainText and HTML for full-text search, including Title, Description, and Steps to Repro. For details and server/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 that must be met before the bug or product backlog item can be closed.

Before work begins, record clear acceptance criteria so the team and customers share expectations. Acceptance criteria help define acceptance tests and confirm whether the item is complete.

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 assigned to a work item. IDs are unique across projects within a project collection.

Reference name=System.Id, Data type=Integer

All

Repro Steps (or Steps to reproduce) 1

Steps required to reproduce unexpected behavior. Capture enough detail so others can reproduce and validate fixes.

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 software and system configuration relevant to the bug or feedback.

Reference name=Microsoft.VSTS.TCM.SystemInfo, Data type=HTML

Bug, Code Review Request, Feedback Request

Team Project

The project that owns the work item. Add this field to a query to filter by one or more projects. For details, see Query across projects.

Reference name=System.TeamProject, Data type=String

All

Title

A short description that summarizes the work item and helps team members distinguish it from others.

Reference name=System.Title, Data type=String

All

Work Item Type

The work item type name, defined by the process used when the project was created. For more information, see About processes and process templates and Add or modify a work item type.

To filter by category assignment, use the In Group and Not In Group operators and select a category from the drop-down.

Reference name=System.WorkItemType, Data type=String

All

Related content

REST API

To programmatically interact with queries, see one of these REST API resources:

  • Last updated on