Manage and organize queries in Azure Boards and Azure DevOps

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

Organize your personal or shared queries by adding a query folder. You can then add queries to or move existing queries into those folders. You can create queries and query folders from the web portal or from a supported client, such as Visual Studio Team Explorer and Team Explorer Everywhere, a plug-in for Eclipse.

Note

To create and manage queries in Visual Studio 2019, you need to Set the Work Items experience to the legacy option.

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 a query

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, edit, and save a query

The easiest way to define a query is to start with an existing shared query. The following example shows how to find all closed bugs by modifying the Active Bugs shared query provided with the Agile process template. Examples are based on the user interface provided through the web portal.

  1. Open a shared query. For example, from the web portal, open the Active Bugs or similar flat list query.

    Run Active bugs query

    Tip

    If you're working in Visual Studio Team Explorer, open the Work page to access your queries and shared queries. If Team Explorer isn't visible, choose View>Team Explorer from the top level menu.

  2. Edit the query to find closed bugs and then run the query. Use Insert new filter line to insert a clause above the current clause. Use Remove this filter line to delete a clause. Queries are automatically scoped to the current project. To find work items defined in several projects, see Query across projects.

    Web portal, Queries page, new queries experience, Editor view of a Flat List Query

  3. Save the query to your My Queries folder.

    Save As query dialog, new experience

    To save a query to the Shared Queries folder, you need to be a member of the Project Administrators group, or have your Contribute permissions on the folder set to Allow. To learn more, see Set query permissions.

  1. Open a shared query. For example, from the web portal, open the Active Bugs or similar flat list query.

    Web portal, Boards>Queries, Open Shared queries, Active Bugs

    Tip

    If you're working in Visual Studio Team Explorer, open the Work page to access your queries and shared queries. If Team Explorer isn't visible, choose View>Team Explorer from the top level menu.

  2. Edit the query to find closed bugs and then run the query. Use Insert new filter line to insert a clause above the current clause. Use Remove this filter line to delete a clause. Queries are automatically scoped to the current project. To find work items defined in several projects, see Query across projects.

    Web portal, Queries page, Editor view of a Flat List Query

  3. Save the query to your My Queries folder.

    Save Query As

    To save a query to the Shared Queries folder, you need to be a member of the Project Administrators group, or have your Contribute permissions on the folder set to Allow. To learn more, see Set query permissions.

Rename or delete a query

From either the Favorites or All page, choose the actions icon of a query to run, edit, rename, or delete the query.

New query experience, Favorites page, query context menu

For shared queries, you can also choose to do one of these tasks:

  • Add to team queries: Select the team to add the query as a team favorite
  • Security...: to set permissions for the query. To learn more, see Set query permissions.
  • Add to dashboard: Adds a Query tile widget to the team dashboard you select. To learn more, see Add widgets to a dashboard.

Choose the context menu icon of a query to edit, rename, or delete the query.

Web portal, Boards>Queries, Open Shared queries, Active Bugs

Add a query folder and move items into a folder

Tip

You need Delete permissions to rename or move a shared query or folder, and Contribute permissions for the folder where you move the query to. To view or set permissions, see Set permissions on queries and query folders.

You add query folders from the Boards>Queries>All page.

  1. Choose All. Expand My Queries or Shared Queries depending on where you want to add a query folder.

  2. To add a folder, choose the actions icon for an existing folder or the top container folder, and choose New folder.

    Open Actions menu, choose New folder

  3. Enter the name for the folder in the New folder dialog. If you want to change the location of the folder, select it from the Folder drop down menu.

    Enter the name and location of the folder.
  4. To move items into a folder, drag-and-drop a query onto the folder.

    Optionally, you can choose More commands for an existing query, choose Edit, and then choose Save As. In the Save query as dialog, choose the folder you want to save the query in.

    Save query as dialog

You add query folders from the Boards>Queries page.

  1. To add a folder, choose the context menu for an existing folder or the top container folder and select New query folder.

    Enter the name for the folder in the New query folder dialog.

    New query folder link on queries context menu

  2. To move items into a folder, drag-and-drop a query onto the folder.

    Optionally, you can choose the context icon for an existing query and choose Rename. In the Rename query dialog, select the folder you want to save the query in.

    Rename query dialog

Add a query to the dashboard or share it with your team

To add a query to a dashboard, open the actions icon (or context icon) menu for the query and add it to a specific dashboard or as a team favorite.

Share queries with your team by adding them to a folder under the Shared Queries container. To save a query to a Shared Queries folder, get added to the project administrators group or have your permissions set for a folder under Shared Queries.

You can only add shared queries to dashboards or as team favorites, and only if you have team administrator or project administrator permissions.