Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020
Use queries to list bugs, user stories, or other work items based on the field criteria you specify. Teams run these lists to triage work, bulk-update items, or review hierarchies. Semantic search offers overlapping and complementary capabilities worth exploring.
Use managed queries to:
- Bulk update 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 teammate
You can create queries and query folders from the web portal or Visual Studio Team Explorer. Changes you make in one client appear in the others because all changes store in the work tracking data store.
Get started using queries
If you're 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 assigned to you, use the @Me macro as the value for the Assigned To field in a clause.
- All valid users with standard access can create queries and folders under My Queries. To create queries or folders under Shared Queries, set the Contribute permission. See Set permissions on queries.
- 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.
- Open any query in Excel to update fields and publish changes to the database.
- Visualize status or progress by creating a pie, column, or trend chart for flat-list queries. For details, see Charts.
Query capabilities
The following sections summarize functions you use to define and manage work item queries.
- Define query filters with the Query Editor.
- Use query macros in clauses to target fields dynamically.
- Manage query results and folders from 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
Queries only support work items and work items linked to other work items. Managed queries do not support:
- Hierarchical views of Test Plans, Test Suites, and Test Cases (these items don't use parent-child links). Instead, view the hierarchy through the Test > Test Plans page.
- Views that show linked objects such as builds, releases, code, or other non-work-item objects.
- Listing work items linked from one project to another.
- Exporting a cross-project query to Excel (direct links queries export as a flat list).
Query types (flat, direct links, tree)
Azure Boards supports three query types; the icon next to a query indicates its type. Choose the type based on the results you need.
Query type
Usage guidance
Flat list of work items
- List items to perform bulk updates
- Triage a list of work items
- Create a query chart and add it to a dashboard
- Create a chart to count items or sum a numeric field
- Export a list to Excel to update fields
Work items and direct links
- List items that depend on other work items
- Find related or dependent items
- List linked work items to do bulk updates
- Triage linked work items, including test-related links
- Find orphaned backlog items (items with no parent)
Note
Work items and direct links queries export to Excel as a flat list. Excel imports them as a flat list because modifying multiple link types in Excel isn't supported.
Tree of work items
- List a tree of Parent-Child related work items or other tree-topology link types
- Triage hierarchical lists of work items
- Export a hierarchical list to Excel to update fields or modify hierarchy
To learn more about link types, see Link type reference.
My Queries, Shared Queries, and Favorites
You alone can view and run queries saved under My Queries. Favorite a query to have it appear in your query selector.
Queries saved under Shared Queries are visible to everyone with project access. Organize shared queries in folders and favorite them for quick access. You can set permissions on 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 provides Favorites and All tabs. Each tab shows a directory view you can filter to find specific queries.
When you navigate the Queries pages, you can open a folder, a subfolder, or a query page.
As you make selections, breadcrumbs appear at the top of the page. Use them to 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
Create pie, bar, pivot, and trend charts from a flat-list query (queries must return 1000 or fewer work items). Add query charts to dashboards, retitle them, and reconfigure them as needed.
Query-based widgets display query information on a dashboard (for example, number of active bugs or an interactive list of work items). To learn more, see:
Add a custom field to support queries
To add a custom field for queries, see Customize your work tracking experience.
Taskboard versus query list items
If taskboard contents differ from a created query's results, see Taskboard items versus query list items for details.
Full-text search queries and collation settings
If you use full-text search queries with the Contains or Contains Words operators, ensure SQL Server collation corresponds to a language with a registered word breaker. Unsupported languages can yield unexpected results.
For more information, see:
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