Query for work items

Last Update: 10/21/2016

Team Services | TFS "15" | TFS 2015 | Previous versions

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

To quickly find a work item by ID, simply enter the ID in the work item search box. Enter a keyword to list items containing the keyword in its title, description, or history.

Otherwise, you can use the Query Editor to craft simple or more complex queries based on the filter clauses you specify. Start by choosing from these three query types:

You can create queries in Team Services, the web portal for Team Foundation Server (TFS), and Team Explorer. Also, you can open a query in Excel or Project to perform bulk additions and modifications.

To view example queries, see Example queries.

Search work items or code

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

Search Work Items Text Box

Use the context menu icon context menu to add a filter based on assignment or workflow change](query-by-workflow-changes.md) status, a keyword, or a work item type.

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

Feature availability: You can add the Code Search extension to Team Services or by upgrading to TFS "15".

If you've added the Code Search marketplace extension, you'll notice that the search box moves to the top row, and you can quickly switch between work item and code searches.

Search Work Items Text Box

The search box retains the last used search context for each hub. Go here to learn more about code search.

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, open the Active Bugs or similar flat list query.

    Open shared 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 this filter line 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.

    Team Services:

    Editor view of a Flat List Query - web portal

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

  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 team administrator, a member of the Project Administrators group, or have your Contribute permissions on the folder set to Allow.

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.

Open a New Query

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.

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.

Results List Showing a Tree Query

Expand (Expand node (Expand node, web portal) or collapse (Collapse node, web portal) leaf nodes to focus on different parts of the tree.

Define the filter criteria for both parent and child work items.

Alt text

To find linked children, select Match top-level work items first. To find linked parents, select Match linked work items first.

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 Plans page of the Test hub.

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

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.

Query variables

The operators and variables available for selection depend on the field that you select. The five variables are:

  • [Any] specifies any value when filtering on the Work Item Type field
  • @CurrentIteration specifies the current sprint for the selected team when filtering on the Iteration Path (works only from the web portal)
  • @Me specifies your user or account name when filtering on a person-name field
  • @Project specifies the current project when filtering on the Team Project field
  • @Today specifies the current date when filtering on a date-time field.

That's the basics about using queries. Refer to one of the following topics for more details and examples:

Add or change columns

To add or remove columns or change the result sort order, open Column Options.

Display Columns Tab in Column Options Dialog

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.

Add a query to the dashboard or share it your team

To add a query to the home page or a dashboard, open the Context Menu Icon 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.

From the Team Explorer plug-in for Visual Studio, you can indent (Indent), outdent (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.

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 Query for Bugs, Tasks, and Other Work Items.

Team Services 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.

Note: Most browsers enforce a limit of between 2000 and 2083 characters for a URL string.

Team Services syntax

https://{youraccount}.visualstudio.com/DefaultCollection/{TeamProjectName}/{TeamName}/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage]

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

https://{ServerName}/{CollectionName}/{TeamProjectName}/_workitems?_a=query&wiql={Encoded WorkItemQueryLanguage]

The _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:

   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'

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.

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?

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

Programmatically query for work items

You can create dynamic queries using one of the following resources: