Track your work by using managed queries in Azure Boards

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

List bugs, user stories, or other work items based on field criteria you specify using queries. You can then review these lists with your team, triage work, or bulk update work items. Along with managed queries, the semantic search tool provides some overlapping and different functionality worth exploring.

Use managed queries to support these operations:

  • Bulk update of work items using the web portal
  • Triage and update work items
  • Review a hierarchy of work items
  • Share a list of work items with a team member

You can create queries and query folders from the web portal or from Visual Studio Team Explorer. Changes you make in one client are reflected in other clients as all changes are stored in the work tracking data store.

Get started using queries

If you're just getting started, read View, run, or email a work item query. For a quick reference to query editor tasks and sample queries, see Query quick reference.

  • To find work items that are assigned to you, add the @Me macros as the value for the Assigned To field in one of the query clauses.
  • All valid users with standard access can create queries and folders under the My Queries area. To create queries and query folders under Shared Queries, you must have the Contribute permission set. For more information, see Set permissions on queries.
  • You can modify any query by adding criteria to focus on a product area, an iteration, or another field. To modify a query, open the query editor.
  • You can open any query in Excel. You can also update the fields of one or more work items and publish your changes to the database for tracking work items.
  • You can visualize status or progress by creating a pie-chart, column chart, or trend chart for flat-list queries.

Query capabilities

The following sections provide an overview of the functions supported to define and manage work item queries.

  • Query filters are defined through the Query Editor.
  • Query macros can be selected for specific fields to create a query clause.
  • Query results and query management features are capabilities available through the Query Results page.

Query filters

The following table summarizes the query filter functions supported by each Azure DevOps version.

Note

Managed queries don't support proximity searches, however semantic searches do. In addition, semantic searches support both * and ? as wildcard characters and you can use more than one wildcard character to match more than one character. For more information, see Functional work items search.


Filter function

Query support

Supported versions


Text string searches (single text, multi-line text, rich text)

Searches are not case sensitive.

All versions


Wild card = *

All versions


Find work items based on direct links or topological/hierarchical link types.
Filter linked work items based on MODE (WIQL syntax)

All versions


Group and nest clauses using AND and OR Boolean operators.

All versions


Find work items based on a field match with a previous value. Supported operator: Was Ever Find work items based on a value defined on a specific date. Supported operator: ASOF (WIQL syntax)

All versions


Use macros to create queries relative to a date, other tools, such as team area path, team iteration, and more.

All versions


Find work items in one or more projects in an organization or collection. Default is the current project. Use the Team Project field to query on two or more projects.

All versions


Find work items based on how two fields compare with one another.
Supported operators: =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field]

All versions


Find work items based on whether they contain or don't contain a tag. Supported operators: Contains, Does Not Contain

All versions


Find work items based on empty or not empty HTML/rich text fields.
Supported operators: Is Empty, Is Not Empty

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services


Find work whose field value matches any value in a delimited set, such as a set of work item types, workflow states, or picklist values. 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(,).

All versions


Find work items based on boolean field value.

All versions


Find work items based on key words or phrases added through the Discussion.

All versions


Find work items based on their Kanban column, swimlane, or Doing/Done status.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services


Filter query results based on a key word or select fields.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services


To bulk move, copy, or paste query clauses, install and use the WIQL editor.

Supported macros

The following table summarizes the query macros or variables supported by the Azure DevOps versions. You can use some of these macros to filter notifications.

Note

You can use certain macros from the web portal only. These include the @CurrentIteration, @CurrentIteration +/- n, @Follows, @MyRecentActivity, @RecentMentions, @RecentProjectActivity, and @TeamAreas macros. These macros aren't supported when exporting a query to Excel, notification filters, or exercised from Team Explorer, or REST APIs.

For more detailed descriptions and links to examples, see Query fields, operators, and macros.


Macro

Query support

Supported versions


Find any work item type, Work Item Type=[Any], or any State, State=[Any].

All versions


@Me

Find work where Identity field=logged in user.

All versions


Find work where Date-Time field=today.

All versions


Find work defined in one or more projects.

All versions


Find work defined in current iteration for a team.

All versions


Find work defined in +/- n of current iteration for a team.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services


Find work current logged in user is following, ID In @Follows.

All versions


Find work items recently changed, ID In @MyRecentActivity See also View and add work items, Work Items page.

All versions


Find work where the selected date-time field is within the current day, month, week, or year with a plus/minus offset, example: Closed Date>=@StartOfDay-7.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services


Find work assigned to an Area Path or Iteration Path of specified team, for examples, see Query by area or iteration path.

Azure DevOps 2019 through Azure DevOps Server 2022, Azure DevOps Services


Query results and query management features

The following features provide support for working with query results, saving and sharing queries, and more.



Unsupported features

Work item queries only support querying of work items and work items linked to other work items. Here are a few of the tasks that managed queries don't support:

  • Hierarchical views of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. Instead, you can view the hierarchy through the Test>Test Plans page.
  • Views showing linked objects such as builds, releases, code, or other non-work item objects.
  • List work items linked from one project to another.
  • Export a cross-project query to Excel. Direct links queries export to Excel as a flat-list.

Azure Boards supports three query types. The icon next to each query indicates the query type. Use the following guidance to choose the query type based on what you want to accomplish with the query.

Query type icon list


Query type

Usage guidance


Flat list of work items

  • List items to do bulk updates to fields
  • Triage a list of work items
  • Create a query chart and add it to a dashboard
  • Create a chart to get a count of items or sum a field
  • Export a list of items to Excel to update fields

Work items and direct links

  • List items that are dependent on other work items
  • Find items related or dependent on other work items
  • List linked work items to do bulk updates to fields
  • Triage a list of linked work items
  • List test-related linked work items
  • Find orphaned backlog items, work items that have no parent

Note

Work items and direct links queries export to Excel as a flat list. Direct links queries are imported as a flat list as modifying multiple types of links isn't a supported feature in Excel.


Tree of work items

  • List a tree of Parent-Child related work items, or other tree-topology link type
  • Triage a hierarchical list of work items
  • Export a hierarchical list of items to Excel to update fields or modify the hierarchy

To learn more about link types, see Link type reference.

My Queries, Shared Queries, and Favorites

Only you can view and run queries that you save under My Queries with the queries directory. Also, you can favorite one of these queries to have it appear within your query selector.

Queries you and others save under Shared Queries can be viewed by everyone with access to the project. Shared queries can be organized within folders and favorited by you or for a team. Also, you can set permissions on the folders and queries to prevent others from moving or editing them.

For more information, see:

Query directory, query folders, and breadcrumbs

The Queries page contains a directory-focused view that you can filter to find specific queries of interest. When working in the Queries pages, you can go to a subfolder, folder, or page.

Queries breadcrumbs

Also, you can choose a query that you've favorited from the selector menu. Or, you can choose to browse all queries that return you to the All Queries page.

Screenshot of Queries, Query selector.

For more information, see Query FAQs, Navigate, and Folders.

Query charts and widgets

You can quickly create pie, bar, pivot, and trend charts from a flat-list query. Queries must be flat-list and return 1000 or less work items. You can add your query charts to a dashboard, retitle, and reconfigure them.

Example pie chart. Example pivot chart. Example bar chart. Example trend chart.

Query-based widgets provide support for presenting query information on a dashboard. For example, the number of active bugs or a list of work items that you can interact with. To learn about query charts and widgets, see these articles:

Add a custom field to support queries

To add a custom field to support your query needs, see Customize your work tracking experience.

Taskboard versus query list items

You may notice and wonder why the contents of the taskboard differ from the contents listed with its created query? For more information, see taskboard items versus query list items.

Full-text search queries and collation settings

To support full-text search queries, the collation settings of the SQL Server database should correspond to a language that has a word breaker registered with SQL Server. If you use an unsupported language, you could receive unexpected results when you run a work item query that specifies the Contains or Contains Words operators with text strings.

For more information, see the following articles:

REST API

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