Edit

Share via

Query by area or iteration path

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

The Area Path and Iteration Path are two fields that appear on the work tracking form for all work item types. You define them for a project—area paths and iteration paths—and then select the ones you want to associate with a team.

To better understand how to work with area and iteration paths, see About teams and Agile tools.

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.

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.

Supported operators and macros

When creating queries and specifying the Area Path and Iteration Path fields, you can use the following operators:

Operator Use when you want to...
= Specify one specific area or iteration path
<> Filter out one, specific area or iteration path.
In Filter for a set of area or iteration paths.
Not In Exclude items that are assigned to a set of area or iteration paths.
Under Specify all paths under a selected area or iteration path.
Not Under Exclude items assigned under a specific area or iteration path.

Along with these operators, you can use the following macros when you select the Iteration Path. For examples, see the query examples on this page.

Macro Use when you want to...
@CurrentIteration Specify the current iteration associated with the selected team context.
@CurrentIteration +/- n Filter items based on assignment to a sliding window of sprints associated with the selected team context.
@TeamAreas Filter items based on area path(s) assigned to a specific team.

Note

Macros such as @CurrentIteration, @CurrentIteration +/- n, and @TeamAreas get evaluated only by the Azure DevOps web portal (Services and Server). Nonweb clients (Visual Studio/Team Explorer, Excel, Project) and direct WIQL/REST calls require explicit area/iteration paths and don't accept raw macro tokens. When you save a query in the web UI, the portal usually expands macros to concrete values in the stored WIQL—verify this behavior in your environment if you need to use queries outside the web UI.

Area path queries

You can specify to filter for work items assigned to several area paths by using the In operator as shown in the following example.

Screenshot that shows a query on Area Path for several areas.

Node Name and keyword-based queries

Use the Node Name field to filter on work items assigned to area paths based on a keyword using the Contains operator. The Node Name specifies the last node of an Area Path, which corresponds to the last node in the tree hierarchy.

The following query yields the same result as the previous example.

Screenshot that shows a query on Node Name for several areas.

In this example, the filter returns any work items assigned to an area path whose last node contains the word "Azure."

Screenshot that shows a query for several sprints.

Here's another example that uses the Node Name and the In operator.

Screenshot that shows a query on Node Name for several areas.

Team area path queries

Use the @TeamAreas macro to quickly find items assigned to the area paths assigned to a specific team. Specify the = operator. The Query Editor prompts you to enter the team name; select the team from the suggested list.

Screenshot that shows a query on area paths assigned to a team.

Classification field reference

Field name Description Reference name
Area Path Groups work items into product feature or team areas. The area must be a valid node in the project hierarchy. System.AreaPath
Iteration Path Groups work items by named sprints or time periods. The iteration must be a valid node in the project hierarchy. System.IterationPath

For each field, data path=TreePath, reportable type=Dimension, index attribute=True.

If you define a path name that is longer than 256 characters, you can't specify it in Microsoft Project. To avoid this problem, define path names of no more than 10 characters, and don't nest nodes more than 14 levels deep.

You can't apply most field rules to system fields, such as System.AreaPath and System.IterationPath fields. For more information, see Rules and rule evaluation.

The following fields don't appear on work item forms but are tracked for each work item type. These fields provide a numeric value for each classification value that is defined for a project. You can use these fields to filter queries and create reports.

Field name Description Reference name Data type
Area ID The unique ID of the area to which this work item is assigned. System.AreaId Integer
Iteration ID The unique ID of the iteration to which this work item is assigned. System.IterationId Integer
Node Name The name of the last node of an area path. For example, if the area path is Project\A1\B2\C3, the node name is C3. System.NodeName String

The default reportable type is none. Area ID and Iteration ID are indexed. Node Name isn't. To learn more about field attributes, see Work item fields and attributes.

Related content

REST API

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