Query fields, operators, and macros

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

This article provides descriptions of each field data type, query operator, and query macro. Some data types, operators, and macros are only valid for the indicated Azure DevOps version.

For more information, see Query quick reference and Manage and organize queries.

Prerequisites

• Access levels:
  • To view and run shared queries, be a project member.
  • To add and save a shared query, have at least Basic access.
• Permissions: Have your 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.

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

Boolean

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 01/01/2025. 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 more information, 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.

picklistDouble

Custom field defined to contain a pick list of Decimal values.

picklistInteger

Custom field defined to contain a pick list of Integer values.

picklistString

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 are equal to, not equal to, under, or not under a tree structure. You can also use the In or Not In operators to specify multiple values. 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 picklist... data types are only assigned to custom fields defined for an inherited process.

Date and time pattern

The date and time pattern you enter for DateTime fields should match that which you select through your profile. To view or change your selection, see Set user preferences.

Query operators

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.

For more information, see Define a query.

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
Checks if the Boolean field is equal to another 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
Checks if the Boolean field isn't equal to another 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 and Azure DevOps Server.

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 and Azure DevOps Server.

HTML

Not In

Doesn't match any value in a delimited set. You can exclude work items whose states aren't 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 supported for Azure Boards and Azure DevOps Server.

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 Microsoft Entra ID when your Azure Boards account is backed by Microsoft Entra ID, or Active Directory when your on-premises server instance is backed by Active Directory.

For information, 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 Azure DevOps 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 Microsoft Entra ID when your Azure Boards account is backed by Microsoft Entra ID, 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

Note

Was Ever on date fields isn't currently supported when using the Query Editor. They're only supported when doing a direct WIQL.

Tip

It's possible to construct 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] doesn'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 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 when run from the web portal.

---

@Follows

Use with the ID field and In operator to list all work items that you're following in the project. For more information, 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 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 board changes.

---

@MyRecentActivity

Use with the ID field and In operator to list work items you 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 system automatically defaults to filtering based on the current project. For more information, see Define a query, Query across projects.

---

@RecentMentions

Use with the ID field and In operator to list work items where you're 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 recently updated. The number of work items listed depends on the work tracking activity of the project. For highly active projects, the macro lists work items updated in the project within the last 30 days or so. For less active projects, however, this list could include work items older than 30 days. You can view similar lists from the Work Items page, Recently created, Recently updated and Recently completed pivot views. The number of work items returned is capped at 5000.

---

@StartOfDay

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

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

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

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 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.

---

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 only see the Contains and Does not Contain operators.

Related articles

• Use the query quick reference
• Learn about managed queries
• Access the work item field index
• Understand the syntax for the Work Item Query Language (WIQL)

REST API

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

• Azure DevOps Services REST API Reference
• Queries
• Work item query language
• Fetch work items with queries programmatically