Query fields, operators, and macros in Azure Boards

Description

Specifies a field that takes on a True/False value.

A date field in which you can specify a variable, such as @Today or @Today-1, or a value, such as 1/1/2023. 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).

A real number, such as 0.2 or 3.5. For query examples, see Query by numeric fields.

A character string that represents a unique ID.

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.

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.

Short text string that identifies a user identity.

A 32-bit integer that is signed, such as 0, 1, 2, 34.

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.

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

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

Custom field defined to contain a pick list of short text string (255 characters or less) values.

Short text string that can contain up to 255 Unicode characters. String text fields are often used to support picklists or drop-down menus.

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.

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

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

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

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

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

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

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 an exact or partial match of the text string within the field you selected for filtering.

String

Doesn't contain an exact or partial match of the text string within the field you selected for filtering.

String

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.

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.

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

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

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

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

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.

For information about category groups, see Use categories to group work item types.

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.

Doesn't match the value in the clause and isn't contained under the node in the clause.

TreePath

Matches the value in the clause or is contained under the node in the clause.

TreePath

Matches the value in the clause at any previous point.

String , DateTime

Description

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.

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.

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.

Use with the ID field and In operator to list all work items that you're 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 only when run from the web portal.

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.

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.

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.

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.

Use with the ID field and In operator to list work items that have been 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 that have been 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.

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.

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.

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.

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.

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.

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.