Query for work items

Go here to open the Visual Studio 2015 version of this topic.

Queries help you find work items that you want to review, triage, update, or generate a report.

Use the search box to find work items. Enter the ID or use filters. If you want a flat list of work items, a hierarchical list using a tree query, or a list showing dependencies using a direct links query, use the query editor to choose the query type.

You can create queries in Visual Studio Online, Team Web Access (TWA), and Team Explorer. Also, you can open a query in Excel or Project to perform bulk modifications.

Use the search box to find a work item by its ID

Type the ID in the Search work items box and then choose the search icon.

Using the context menu, you can add filters to list items based on assignment, status, a keyword, or a work item type.

For example, enter A=@Me T=Task to list all tasks assigned to you.

Open and edit a flat list 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 browser.

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

   

      

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 filter line) to delete a clause.

   

      

3. 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.

Create a query

Start from the New menu on the queries page in TWA, or work items page in Team Explorer.

Group clauses to refine your list

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 a hierarchical list

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 () 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.

Use a direct link query 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.

Q & A

Q: What query operators and variables can I use?

A: The operators and variables available for selection depend on the field that you select. The four variables are @Project for the project name field, @Me for person-name fields, @Today for date-time fields, and [Any]. See Query fields, operators, values, and variables.

Q: What other query examples are there?

A: See Example work item queries and Example search box queries.

Q: How do I chart the results of a query?

A: From Visual Studio Online and TWA, you can chart the results of any flat-list query. You must be a member of the Advanced access group in TWA.

Or, you can open a query in Excel and use the features of Excel to generate a chart.

Q: How do I automatically update queries based on the current sprint or iteration?

A: There’s no automatic way to do this; you must manually update queries to point to the current sprint. If your team project is based on Scrum or Agile, you’ll find a set of queries under the Current Sprint or Current Iteration folders. For each query to return items defined for the current sprint, you must update the iteration path to the iteration that is current according to the date.

You can change many of your queries by saving them as .wiq files. Open the query in Team Explorer, choose Edit Query, and then choose File, Save As to save each query as a .wiq file. Here is an example of the Work in Progress query that has been updated to support Release 2\Sprint 59.

<?xml version="1.0" encoding="utf-8"?>
<WorkItemQuery Version="1">
  <Wiql>
    SELECT [System.Id],
           [System.WorkItemType],
           [System.Title],
           [System.AssignedTo],
           [System.State],
           [Microsoft.VSTS.Scheduling.RemainingWork],
    FROM WorkItems 
      WHERE [System.TeamProject] = @project and 
            [System.IterationPath] under 'FabrikamPrime\Release 2\Sprint 59' and 
            [System.WorkItemType] in group 'Microsoft.TaskCategory' and 
            [System.State] = 'In Progress' 
      ORDER BY [System.AssignedTo],
               [Microsoft.VSTS.Common.BacklogPriority],
               [System.Id] 
   </Wiql>
</WorkItemQuery>

Q: How do I add or change columns in the results list?

A: Open Column Options to add or remove columns, change the sequence of columns, and change the sort order within a column.

Also, from the results list, you can drag a column to a new position and select the column title to change the sort order by column.

Q: Can I filter a query using tags?

A: Yes if you’re using Visual Studio Online or if your on-premises TFS contains the updates added with TFS 2013 Update 2, otherwise, no for on-premises deployments.

For Visual Studio Online and with Visual Studio 2013 Update 2, you can choose Tags as a field to filter on. Also, you can open a query from Excel and bulk modify tags assigned to work items. You can also add tags to work items using Visual Studio.

From the Team Explorer plug-in for Eclipse, you can filter queries by tags, however, you can’t add or modify tags from the user interface. You must use the web portal to add and modify tags.

For on-premises TFS without TFS 2013 Update 2, you can show tags as a column in the query results and you can filter a list based on a tag, however, you can’t add tags as a clause to the filter criteria.

Q: Can I use query results to quickly modify linked relationships?

A: From the Team Explorer plug-in for Visual Studio, you can indent (), outdent (), and drag work items to modify the hierarchy.

Also, you can open a query in Excel or Project to bulk-modify parent-child and predecessor-successor link relationships.

Q: How do I prevent someone from changing a query I share with the team?

A: Set the permissions on the query to Read.

Q: How do I add a query to Shared Queries or as a team favorite?

A: To save a query to the Shared Queries folder, get added to the project administrators group or have your permissions set for a folder under Shared Queries.

To add a query as a team favorite, open the context menu for the query and add it as a team favorite. You need to be a team administrator to add queries to team favorites.

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

Q: Can I add folders to team favorites?

A: No. You can only add folders under My Queries and under Shared Queries.

Q: Can I email a query?

A: Yes. See Email URL links to TFS work items and queries.

Q: Can I define a hyperlink that opens a query?

A: Yes. 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, and matches this syntax:

**http://ServerName:**Port/ /tfs/CollectionName/TeamProjectName/**q.aspx?pname=Project&wiql=**WorkItemQueryLanguage

For example, the following hyperlink lists the ID, title, and state of all bugs that have build number 9.0.30304 defined for the AdventureWorksProject project.

http://AdventureWorks:8080/tfs/ /q.aspx?pname=AdventureWorksProject&wiql==SELECT [System.ID], [System.Title], [System.State] FROM WorkItems WHERE [System.TeamProject]='AdventureWorksProject' AND [System.WorkItemType]='Bug' AND [System.FoundIn]='9.0.30304' http://Server1:8091/tfs/web/wi.aspx?id=9035

Q: Can I export a query?

A: Yes. 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 the process template.

Q: Why do the contents of the task board differ from those listed with its created query?

A: It’s possible to assign tasks to an iteration but not have them linked to a parent backlog item. These items will show up in the created query, but will not show up on the task board itself. TFS runs the query and then applies a few background processes before displaying the task board items.

These three reasons can cause work items that belong to the Task Category to not appear on a sprint backlog or task board:

• The task hasn’t been linked to a parent backlog item. Only those bugs and tasks that you have linked to a parent product backlog item (Scrum), user story (Agile), or requirement (CMMI) whose iteration path is set to the sprint will appear on the sprint backlog page.

• The task is a parent of another task. If you’ve created a hierarchy of tasks, only the child-level tasks at the bottom of the hierarchy appear.

• The task’s linked parent corresponds to a backlog item defined for another team. Or, the area path of the task’s parent backlog item differs from the task’s area path.

Q: Can I programmatically query for work items? Can I create a dynamic query?

A: Yes. See Query for Bugs, Tasks, and Other Work Items.

See Also

Concepts

Choose the Team Foundation client to support your tasks