View, run, or email a work item query

Azure Boards | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2013

Visual Studio 2019 | Visual Studio 2017 | Visual Studio 2015 | Visual Studio 2013

To find work items assigned to you or your team, run a query. Many work item queries are predefined with your process. Members of your team may have created shared queries that you can view and run. Often, it's easier to define a new query by building on the query definition that's already available to you.

Prerequisites

  • By default, all project members and users with Stakeholder access can view and run all shared queries. You can change the permissions set for a shared query folder or shared query. For details, see Set query permissions.
  • To add and save a query under Shared queries, you must be granted Basic access or higher. Also, you must have your Contribute permission set to Allow for the folder you want to add the 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 details, see Stakeholder access quick reference.

  • By default, all project members and users with Stakeholder access can view and run all shared queries. You can change the permissions set for a shared query folder or shared query. For details, see Set query permissions.
  • To add and save a query under Shared queries, you must be granted Basic access or higher. Also, you must have your Contribute permission set to Allow for the folder you want to add the query to. By default, the Contributors group doesn't have this permission.

Open Queries

From your web browser, (1) check that you have selected the right project, (2) choose Boards>Queries, and then (3) choose All.

Open Boards>Queries, vertical nav

If it is your first time opening Queries, the page opens to Favorites. This page lists those queries that you have indicated are a favorite. Otherwise, you can choose All to view all queries you've defined and shared queries defined for the project.

Tip

Queries you or your team have chosen as favorites show up on the Favorites page. Favorite queries along with other objects also appear on your Project page. To learn more, see Set personal or team favorites.

From your web browser, open Boards>Queries.

From your web browser, open Boards>Queries

Run a query in Azure Boards

To run any query, expand a folder and choose the title of the query. The view opens to display the query Results.

You can also run a query by using the Azure DevOps command line interface.

Tip

The Queries page, as with other web portal pages, remembers the view you last navigated to and returns you to that view.

  1. Choose All to open the page where you can view all queries you've defined or that are shared within your project.

    Web portal, choose Boards>Queries>All page

  2. Choose My Queries as needed.

    • To view all work items assigned to you, choose Assigned to me. This query uses the @Me macro to list all work items assigned to you.
    • To view all work items you're following, choose Followed work items. This query uses the @Follows macro (ID in @Follows) to list all work items you've chosen to follow. To learn more, see Follow a work item or pull request.
  3. Choose Shared Queries to expand the folder and access queries saved as shared queries.

  4. Choose a folder within a breadcrumb to open a query folder.

    Screenshot of queries breadcrumb example.

Run a query from the command line

You can run a query in the CLI with the az boards query command. To get started, see Get started with Azure DevOps CLI.

az boards query [--id]
                [--org]
                [--path]
                [--project]
                [--wiql] 

Parameters

  • id: The ID of an existing query. Required unless--path or--wiql is specified.
  • wiql: The query in Work Item Query Language format. Ignored if--id or--path is specified.
  • path: The path of an existing query. Ignored if--id is specified.
  • org: Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL. Required if not configured as default or picked up using git config. Example: --org https://dev.azure.com/MyOrganizationName/.
  • project: Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID. Required if not configured as default or picked up using git config.

Example

The following command runs a query with the specified ID and shows the result in table format.

az boards query --id 6c286d74-26a5-4cce-bfcf-bf9123495bfe  --output table

Priority    Node Name         Work Item Type    Title                             Remaining Work
----------  ----------------  ----------------  --------------------------------  ----------------
1           Voice             Bug               Apply fix elsewhere as needed
2           CMMI              Bug               Slow response on form
1           Fiber             Bug               Check issues with permissions     0
2           Fiber             Bug               Voicemail hang issue              0
2           FabrikamBB        Bug               Research slow response time
1           FabrikamBB        Bug               Fix performance issues            0 

The following command runs a query with the specified WIQL and shows the result in table format.

az boards query --wiql "SELECT [Microsoft.VSTS.Common.Priority], [System.NodeName], [System.WorkItemType], [System.Title], [Microsoft.VSTS.Scheduling.RemainingWork], [System.AssignedTo], [System.State], [System.Tags], [System.AreaPath] FROM workitems WHERE [System.WorkItemType] = 'Bug' AND [System.AreaPath] = 'Fabrikam Fiber' ORDER BY [System.WorkItemType]" --output table

Priority    Node Name       Work Item Type    Title                  Remaining Work
----------  --------------  ----------------  ----------------       ----------------
2           Fabrikam Fiber  Bug               Slow response on form
2           Fabrikam Fiber  Bug               Check permissions
2           Fabrikam Fiber  Bug               Fix performance issue
2           Fabrikam Fiber  Bug               Secure Sign-in 

Query directory, query folders, and breadcrumbs

Query folders

Note

You can't add folders to My Favorites or Team Favorites.

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 navigate 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, which returns you to the All Queries page.

Screenshot of Queries, Query selector.

The Queries page displays the folder structure in the left pane. You can expand and collapse folders, rename folders, and drag and drop queries from one folder to another. To learn more, see Manage and organize queries.

Screenshot of Queries page, TFS 2018 and earlier versions.

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

All and Favorites supported tasks

You can do most tasks for viewing and running queries from each of the queries list pages as indicated in the following table. Only queries you save under My Queries and have favorited show up under My Favorites. Only queries saved under Shared Queries can be favorited by a team.


Task
Favorites
(Browser)
All
(Browser)
Work Items
(Team Explorer)
View all favorited queries, yours or a team you belong to ✔️ ✔️
View all your queries or shared queries for the current project ✔️ ✔️
Run a query, open the context menu for a query ✔️ ✔️ ✔️
Expand or collapse container folders or query folders ✔️ ✔️ ✔️
Filter the list of queries ✔️ ✔️
Favorite a query (for web portal, choose Favorite) ✔️
Unfavorite a query (for web portal, choose ) ✔️ ✔️ ✔️
Add a new query: Choose ✔️ ✔️ ✔️

Filter the list of queries

Enter a keyword into the filter box to filter the set of queries displayed on either the Favorites or All pages. To learn more about filtering, see Filter backlogs, boards, queries, and plans.

Screenshot showing all queries in the project filtered by WIT IQ keyword criteria.

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

Email query items or share a query URL

From the Query Editor or Results view, you can email a formatted list of query items or copy the query URL.

Choose the actions icon to open the menu and select from the options listed, Email query or Copy query URL.

Web portal, Query Editor/Results, Open Actions menu, Choose Email query or Copy query URL
You can only send the email to individual address for a project member that is recognized by the system. Adding a team group or security group to the to line isn't supported. If you add an email account that the system doesn't recognize, you receive a message that one or more recipients of your email don't have permissions to read the mailed work items.

Note

To email a formatted list to people who aren't project members, you'll need to use the Copy as HTML option described in Copy a list of work items. For on-premises Azure DevOps, all email actions require an SMTP server to be configured. If you don't have an SMTP server configured, you can work around this by using Copy as HTML.

Choose Copy query URL. To email query items, see Copy a list of work items.

Web portal, Query Editor/Results, Copy query URL

Note

With Email query, the system will email the formatted list to those teammates you select. To email a formatted list to people not part of the project, you'll need to use the Copy as HTML option described in Copy a list of work items. All email actions require an SMTP server to be configured. If you don't have an SMTP server configured, you can work around this by using Copy as HTML.

Try this next