VSTS | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013
For details on constructing query clauses and information on each query operator—such as,
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 team projects
The images you see from your web portal may differ from the images you see in this topic. These differences result from updates made to VSTSor your on-premises TFS, options that you or your admin have enabled, and which process was chosen when creating your team project—Agile, Scrum, or CMMI. However, the basic functionality available to you remains the same unless explicitly mentioned.
Work items are denoted with icons for VSTS and TFS 2017.2 and later versions. For an overview of changes in the navigation experience and working within the user and administration contexts, see Work in the web portal.
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.
Open a shared query. For example, from the web portal, open the Active Bugs or similar flat list query.
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, click View>Team Explorer from the top level menu.
Edit the query to find closed bugs and then run the query. Use to insert a clause above the current clause. Use to delete a clause. Queries are automatically scoped to the current team project. To find work items defined in several team projects, see Query across team projects.
VSTS, TFS 2017, TFS 2015:
Save the query to your My Queries folder.
To save a query to the Shared Queries folder, you need to be a team administrator, 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 page in the web portal or the Work Items page in Team Explorer.
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|
|Priority = 1 OR (Work Item Type=Bug AND State=Active)|
|Priority = 1 AND (Work Item Type=Bug OR State=Active)|
To group one or more clauses, select them and then choose the group clauses icon.
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 () 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 () or collapse () leaf nodes to focus on different parts of the tree.
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.
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 Plans page of the Test hub.
Use direct links to view dependencies
Use the 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.
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.
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 team projects
By default, shared queries and new queries are scoped to the current team project. However, you can create queries to find work items defined within the team project collection. You save cross-project queries under a specific team project.
Feature availability: The Query across projects feature is supported from VSTS and the web portal for TFS 2015.1 or later version.
VSTS and TFS 2015.1
To list work items defined in two or more team projects, checkmark Query across projects. For example, the following query finds all features created in all team projects within the last 30 days.
With the Query across projects checked, you can add the Team Project field to filter to a select number of team projects.
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 team project appear in the Field drop-down menu. When Query across projects is checked, all fields from all WITs defined in all team projects in the collection appear in the Field drop-down menu.
TFS 2015, TFS 2013
To find all features created in all team projects within the last 30 days, remove the Team Project=@Project clause from the query.
All fields from all WITs defined in all team 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 team project.
Add a query to the dashboard or share it with your team
To add a query to the home page or a dashboard, open the context 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 space. 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.
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.
- Adhoc versus managed queries
- Add work items
- Work item field index
- Chart a flat-list query
- Create Excel reports from a query (TFS)
- Change column options
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 team project, the shared queries are created based on .wiq files defined in a process.
Define a query as a hyperlink
The easiest way to define a hyperlink is to create a query that matches what you want and then copy the URL for the query. The hyperlink uses the work item query language (WIQL), which resembles Transact-SQL. For details about constructing WIQLs, see Syntax for the Work Item Query Language (WIQL).
VSTS and TFS 2015 require that you encode the WIQL portion of the URL syntax. You can use any URL encoder tool to encode your URL.
TFS 2013 and previous versions didn't require encoding.
Most browsers enforce a limit of between 2000 and 2083 characters for a URL string.
For example, the following hyperlink lists the ID and title of all active bugs defined under the FabrikamFiber/Web area path for the fabrikam.visualstudio.com account.
The decoded WIQL conforms to:
SELECT [System.ID], [System.Title] FROM WorkItems WHERE [System.TeamProject]='FabrikamFiber' AND [System.WorkItemType]='Bug' AND [System.State]='Active' AND [System.AreaPath]='FabrikamFiber\Web'
TFS 2015 syntax
_workitems? entry has replaced the
q.aspx? entry used in the syntax for TFS 2013 and previous versions.
For example, the following hyperlink lists the ID, title, and state of all bugs under the FabrikamFiber/Web area path hosted on the fabrikam server.
Which is comparable to the non-encoded entry:
http://fabrikam:8080/tfs/DefaultCollection/FabrikamFiber/_workitems?_a=query&wiql= SELECT [System.ID], [System.Title], [System.State] FROM WorkItems WHERE [System.TeamProject]='FabrikamFiber' AND [System.WorkItemType]='Bug' AND [System.AreaPath]='FabrikamFiber\Web'
TFS 2013 and previous versions syntax
For example, the following hyperlink lists the ID, title, and state of all bugs that have build number 9.0.30304 for the FabrikamFiber team project hosted on the fabrikam server.
http://fabrikam:8080/tfs/DefaultCollection/q.aspx?pname=FabrikamFiber&wiql= SELECT [System.ID], [System.Title], [System.State] FROM WorkItems WHERE [System.TeamProject]='FabrikamFiber' AND [System.WorkItemType]='Bug' AND [System.FoundIn]='9.0.30304'
Programmatically query for work items
You can create dynamic queries using one of the following resources:
- REST APIs: Work item queries and query folders and Work item query language
- SDK: Query for Bugs, Tasks, and Other Work Items.
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.