Create managed queries with the query editor

VSTS | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013

Managed queries generate a list of work items based on the filter criteria you provide. You can create queries from the web portal or from a supported client, such as Visual Studio Team Explorer and Team Explorer Everywhere. Also, you can open a query in Excel or Project to perform bulk additions and modifications.

For details on constructing query clauses and information on each query operator—such as, Contains, In, In Group, and <>(not operator) —and macros, see Query fields, operators, and macros. For an index of example queries, see Create managed queries.

In this topic you'll learn:

  • How to open and edit a query
  • How to add or create a query
  • How to group query clauses
  • Understand when to use a flat-list, tree, or direct-links query
  • How to query across projects

Prerequisites

  • You must connect to a project. If you don't have a project yet, create one in VSTS.
  • You must be a member of the Contributors group or be granted Stakeholder access to add or modify work items. Or, you must have your View work items in this node, and your Edit work items in this node permissions set to Allow.
  • If you haven't been added to a project or team, get added now.

To learn more, see Set permissions and access for work tracking.

  • You must connect to a project. If you don't have a project yet, create one in an on-premises TFS.
  • You must be a member of the Contributors group or be granted Stakeholder access to add or modify work items. Or, you must have your View work items in this node, and your Edit work items in this node permissions set to Allow.
  • If you haven't been added to a project or team, get added now.

To learn more, see Set permissions and access for work tracking.

Open Queries

Note

Choose Previous navigation when you see a top-level blue bar. Choose New navigation if you see a vertical sidebar or if you enabled the New Navigation preview feature. The vertical sidebar, along with other navigational features, is enabled when the New Navigation preview feature has been enabled for the signed-in user or the VSTS organization. To learn how to use the web portal effectively, see Navigation Basics.

For on-premises TFS users, choose Previous Navigation for guidance.

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

Open Work>Queries, vertical nav

If it is your first time opening Work, the page opens to Favorites which lists all queries you have favorited. 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 favorited show up on the Favorites page. Queries you have favorited along with other objects also appear on your Project page. To learn more, see Set personal or team favorites.

New navigation isn't supported on TFS at this time. Choose Previous navigation for guidance.

Open and edit 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

    Web portal, Work>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, new queries experience, Editor view of a Flat List Query

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

    Editor View of a Flat List Query - On-premises TFS

  3. Save the query to your My Queries folder.

    Save As query query dialog, new experience

    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.

Create a query

You can start a fresh, new query from the Queries tab in the web portal or the Work Items tab in Team Explorer.

Add new query, new experience

Queries page, Choose New query from the drop down menu

Group clauses

Grouped clauses operate as a single unit separate from the rest of the query, similar to putting parentheses around a mathematical equation or logic expression. The And or Or operator for the first clause in the group applies to the whole group.

In the next example, the first expression returns all work items that are priority 1 and all active bugs of any priority. The second expression returns all active priority 1 work items and all priority 1 bugs, whether they are active or not.

Grouped clauses Logical expression
Filter Using an OR/AND Operator Priority = 1 OR (Work Item Type=Bug AND State=Active)
Filter Using an AND/OR OR Operator Priority = 1 AND (Work Item Type=Bug OR State=Active)

To group one or more clauses, select them and then choose the Group Query Clause icon group clauses icon.

Web portal, Group Selected Query Clauses

If your query results do not return your expected set of work items, follow these steps:

  • Make sure that each clause is defined as you intended.
  • Verify And/Or assignments to each clause. If your results contain more work items than expected, often an Or clause is present instead of an And clause.
  • Determine if you need to group or change the grouping of the query clauses and the And/Or assignments of each grouped clause.
  • Add more query clauses to refine your query filter criteria.
  • Review the options available to specify fields, operators, and values.

Use a tree query to view hierarchies

Use the tree query (Tree Query) to view a multi-tiered, nested list of work items. For example, you can view all backlog items and their linked tasks. Expand (Expand node (Expand node, web portal) or collapse (Collapse node, web portal) leaf nodes to focus on different parts of the tree.

Results List Showing a Tree Query, new experience

Results List Showing a Tree Query, tfs experience

Results List Showing a Tree Query

Define the filter criteria for both parent and child work items. To find linked children, select Match top-level work items first. To find linked parents, select Match linked work items first.

Tree Query, editor

Tree Query, editor

Note

You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases. These items aren't linked together using parent-child link types. You can view the hierarchy through the Test>Test Plans page.

Use the direct links query (Direct Links Query) to track work items that depend on other tracked work, such as tasks, bugs, issues, or features. For example, you can view backlog items that depend on other items being implemented or a bug being fixed.

Direct Links Query Results

Use the direct links query to track dependencies your team has that other teams work on, or manage commitments your team has made to other teams. Specify the filter criteria for both top and linked work items, and select the types of links used to filter the dependencies.

Direct Links Query, editor

Direct Links Query Editor

Filter your first-tier list of work items by choosing one of these options:

  • Only return work items that have the specified links: First-tier work items are returned, but only if they have links to work items specified by the linked work items filter criteria.

  • Return all top level work items: All first-tier work items are returned regardless of the linked work items filter criteria. Second-tier work items that are linked to the first tier are returned if they match the linked work items filter criteria.

  • Only return work items that do not have the specified links: First-tier work items are returned, but only if they do not have links to work items specified by the linked work items filter criteria.

To learn more about each link type, see Link work items to support traceability and manage dependencies.

Query across projects

By default, shared queries and new queries are scoped to the current project. However, you can create queries to find work items defined within the project collection. You save cross-project queries under a specific project.

To list work items defined in two or more projects, checkmark Query across projects. For example, the following query finds all features created in all projects within the last 30 days.

Web portal, Queries page, Query Editor, Checkbox, Query across projects

Note

The Query across projects feature is supported from TFS 2015.1 and later versions.

With the Query across projects checked, you can add the Team Project field to filter to a select number of projects.

VSTS and TFS 2015.1, Web portal, Query across select projects using the In operator

Note

Separate multiple project names with the list separator that corresponds to the regional settings defined for your client computer, for example, a comma (,).

The Team Project field becomes available only after you check Query across projects. Moreover, when Query across projects is unchecked, only those fields from those WITs defined in the current project appear in the Field drop-down menu. When Query across projects is checked, all fields from all WITs defined in all projects in the collection appear in the Field drop-down menu.

To find all features created in all projects within the last 30 days, remove the Team Project=@Project clause from the query.

TFS 2013-2015, Web portal, Query across select projects using the In operator

All fields from all WITs defined in all projects in the collection always appear in the Field drop-down menu.

Use Team Project=@Project to scope the query to find only those work items defined for the current project.

Task board versus query list items

You may notice and wonder why the contents of the task board differ from those listed with its created query? To learn more, see Task board items versus query list items.

Export a query

From the query editor in Team Explorer, use the File menu to save a query as a .wiq file. When you create a project, the shared queries are created based on .wiq files defined in a process.

See also:

Note

For queries made against VSTS, the WIQL length must not exceed 32K characters. The system won't allow you to create or run queries that exceed that length.

That's the basics about using queries. For an index of query examples, see Create managed queries. To add a custom field to track additional data, see Customize your work tracking experience.

If you want to export a query to Excel, you can do that from Excel or Visual Studio/Team Explorer. Or, to export a query directly from the web portal Queries page, install the VSTS Open in Excel Marketplace extension. This extension will add in Open in Excel link to the toolbar of the query results page.

REST API and SDK resources

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

Or, for TFS 2015 and earlier versions, Query for Bugs, Tasks, and Other Work Items.