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 aren't 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
All versions
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 column, swimlane, or Doing/Done status.
All versions
Filter query results based on a key word or select fields.
All versions
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
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.
All versions
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.
All versions
Find work assigned to an Area Path or Iteration Path of specified team, for examples, see Query by area or iteration path.
All versions
Query results and query management features
The following features provide support for working with query results, saving and sharing queries, and more.
- Add a query chart to a dashboard
- Apply interactive filters
- Choose column sort
- Choose query column options
- Copy query results
- Copy Query URL
- Create query charts
- Create query folders
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.
Query types (flat, direct links, tree)
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
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:
- Manage queries & query folders
- Set query permissions
- Favorite a query and Set personal or team favorites
Query directory, query folders, and breadcrumbs
The Queries page contains a Favorites and an All tab. Each contains a directory-focused view that you can filter to find specific queries of interest.
When you're working in the Queries pages, you can go to a folder, subfolder, or a query page.
As you make selections, the breadcrumbs are shown at the top of the page. You can navigate to a folder, subfolder, or query page.
You can also select a favorite query or return to the All queries page from the drop-down menu of an open query.
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.
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:
- Azure DevOps Services REST API Reference
- Queries
- Work item query language
- Fetch work items with queries programmatically