Edit

Share via

Query by date or current iteration

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

This article shows how to list work items by creation, change, resolution, or closed dates and how to use date macros (for example, @Today) and iteration macros for team sprints. For iteration path fundamentals and client/macro restrictions, see Query by area or iteration path.

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 date macros

Use the following operators and macros for DateTime and Iteration Path fields in Query Editor.

  • DateTime operators: = , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], In, Not In, Was Ever
  • Date macros: @StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear, @Today
    You can combine +/- n with these macros (for example, @Today - 7).
  • Iteration macros: @CurrentIteration and @CurrentIteration +/- n (see the following note and link for client restrictions and team-parameter behavior).

Note

Iteration macros and client restrictions are covered in detail on the iteration page: Query by area or iteration path. If you need queries to run in nonweb clients or via REST/WIQL outside the web UI, verify macro support in your environment and consider expanding macros to explicit paths.

Quick date examples (common queries)

  • Items created in the last 30 days: Screenshot that shows the Query Editor clause for finding items created in the last 30 days.

  • Items modified on a specific date: Screenshot that shows the Query Editor clause for finding items changed on a specific date.

  • Items resolved today: Screenshot that shows the Query Editor clause for finding items resolved today.

  • Items closed within a specified time period: Screenshot that shows the Query Editor clause for finding items closed within a specified time period.

  • Items whose Closed Date is null (not closed): Screenshot that shows the Query Editor clause for finding items whose Closed Date is empty or null.

  • Items whose status changed within the last week: Screenshot that shows the Query Editor clause for items whose status was updated within the last week.

Using the @CurrentIteration macros (short guide)

Use @CurrentIteration to target the team's current sprint and @CurrentIteration +/- n to create a sliding window of sprints (for example, last two, current, and next two sprints). Important points:

  • @CurrentIteration returns items assigned to the current sprint for the team context used when running the query.
  • @CurrentIteration +/- n shifts that window of sprints by n; useful for trend or carry-over analyses.
  • Because macro behavior and client support vary, consult Query by area or iteration path for details about team parameters, which clients evaluate macros, and how macros are stored/expanded when saving queries.

Example images (web portal Query Editor):

Screenshot that shows the Query Editor filter using the CurrentIteration macro with a team parameter.

Screenshot that shows CurrentIteration plus and minus clauses for a sliding window of sprints.

Tip

If @CurrentIteration doesn't return expected results, confirm the team's selected iteration and the iteration date ranges in Team settings.

Date macros: start of day/week/month/year

Start-of macros help build consistent relative date ranges:

  • @StartOfDay, @StartOfWeek, @StartOfMonth, @StartOfYear— use these macros with +/- n to build ranges such as "since start of week" or "last 3 months."
  • These macros get evaluated by the web portal UI; their behavior in nonweb scenarios might differ—test in your target client.

Example queries:

Screenshot that shows the Query Editor clauses for finding items changed in the last 10 days.

Screenshot that shows the Query Editor clauses for features scheduled to be completed in the next three months.

When to use WIQL directly

Use WIQL when:

  • You need advanced operators such as WAS EVER for Iteration Path changes.
  • Query Editor blocks or marks a clause as unsupported (for example, some Was Ever uses). The WIQL Editor extension lets you author those queries and save them.

See Work Item Query Language (WIQL) syntax and the WIQL Editor marketplace extension for examples.

Related content

REST API

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