Specify Query Filter Criteria

You can specify the filter criteria for your query to find work items of interest to you or your team. You can use macros in your query to check what is assigned to you, what your active tasks are, or find those items that were updated recently.

All work item queries consist of one or more query clauses. Each clause includes a field, an operator, and a value. You add, modify and group clauses and fields in queries to find the set of work items of interest to you. Defining a query is often an iterative process, where you adjust your filter criteria until you get the results you want.

In this topic

1. Select the type of query

2. Specify top-level query filter criteria

3. (Optional) Specify filter criteria for linked work items

4. Add, remove, group, or ungroup query clauses

5. Run or cancel a query and check Results

6. Adjust your query filter criteria

Requirements

• You must be a member of the Readers group or have the View work items in this node permission set to Allow. For more information about query permissions, see Query for Bugs, Tasks, or Other Work Items.

1. Select the query type

1. Open your team project, choose the Work Items page, and then choose New Query.

   A new Flat List of Work Items (Default) query opens.

2. On the query toolbar, select the Type of Query based on the type of view or work items that you want to find:

   •  Flat List (Default): Returns a single tier, flat list of work items that match your filter criteria. Use this type of query to find work items that you want to link to other work items, export work items to Office Excel and Office Project for bulk updates to column fields, or generate a report about a set of work items. For more information, see Work with a flat list (default) query.

   • Work Items and Direct Links: Returns a two-tiered set of work items that match your filter criteria and all work items that are linked to them based on secondary filter criteria. This view displays the work items in an expandable/collapsible view. For more information, see Work with linked dependencies (Direct Links).

   •  Tree of Work Items: Returns a multi-tiered set of work items that match your filter criteria and includes all work items that are linked to the top level work items based on parent-child links. This view displays the work items in an expandable and collapsible hierarchical view. For more information, see Work with linked hierarchies (Tree of Work Items).

   For a summary of tasks supported by each query type, see Select the right query tool for the task.

Back to top

2. Specify the top-level query filter criteria

The top-level filter criteria limits the query results to a team project and a work item type.

If you work on several team projects, you may want to search through all of them with a single query.

1. Specify the team project(s) that contain the work items that you want to find. If you want to return work items for:

   • The current team project, keep Team Project=@Project.

   • Another team project, type the name of the team project in the Value column for the Team Project field.

   • Several team projects, enter the values shown in the following table:

     And/Or	Field	Operator	Value
     	Team Project	In	<first team project name>, <second team project name>, ...

     Separate the team project names with commas (,).

2. Specify the type of work items that you want to find. If you want to return work items for:

   • All types, keep Work Item Type=[Any].

   • A single type, choose the Value column for the Work Item Type field, and then choose the type of work item you want.

   • Several types of work items, enter the values shown in the following table:

     And/Or	Field	Operator	Value
     And	Work Item Type	In	<first work item type>, <second work item type >, ...

     Separate the names of each work item type with commas (,).

   • All types of work items that belong to a named category, enter the values shown in the following table:

     And/Or	Field	Operator	Value
     And	Work Item Type	In Group	<name of the work item type group>

     For information about how to define groups of work item types, see Customize the Categories for Work Item Types [witadmin].

     For additional options that you can use to filter top-level criteria, see the "Operators" section in Query Fields, Operators, Values, and Variables.

3. On the query toolbar, choose Run, and confirm that your query returned the results that you expected.

4. Choose Save Query. For more information, see Save, Copy, Rename, and Delete Work Item Queries.

Back to top

3. (Optional) Specify filter criteria for linked work items

If you selected  Work Items and Direct Links or  Tree of Work Items, you can specify the filter criteria for the linked work items as well as which top-tier work items are found.

To specify filter criteria for a Work Items and Direct Links query

1. Select And linked work items that match the query below. Add and group clauses in the same way that you defined them for the top-level criteria.

   Filter criteria for linked work items

   

2. Select an item in Linking Filters to filter your first-tier list of work items:

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

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

3. (Optional) Choose Return selected link types, and then select one or more of the available check boxes for the link types to include in your filter criteria.

4. On the query toolbar, choose Run, and confirm that your query returned the results that you expected.

5. Modify your filter criteria and re-run the query until you get the first and second-tier of work items that you want.

To specify filter critera for a Tree of Work Items

1. Under Filters for linked work items, add and group clauses in the same way that you defined them for the top-level criteria.

2. Select the Linking Filters that will additionally filter your first-tier list of work items as follows:

   1. Match top level work items first: Performs a top-down search. All first-tier work items are returned. All work items that are linked to the first tier are returned if they match the linked work items filter criteria.

   2. Match linked work items first: Performs a bottom-up search. Finds all linked work items, then returns the first-tier work items that are linked to the found items.

3. (Optional) Choose Type of Tree. If you have added custom link types of tree topology, you can choose from the values listed to a custom set of hierarchical link types. See Link Type Element Reference.

4. On the query toolbar, choose Run, and confirm that your query returned the results that you expected.

5. Modify your filter criteria and re-run the query until you get the first and second-tier of work items that you want.

Back to top

4. Add, remove, group, or ungroup query clauses

You can add one new clause for each work item field to refine your search criteria and return only the set of work items that you want. If you do not receive the results that you expect from your query, you can add, remove, group, or ungroup query clauses to refine your query results. For information about the elements in a query clause, see Query Fields, Operators, Values, and Variables.

Each query clause includes a field name, query operator, and value. Use as many clauses as required to obtain useful results.

You can group query clauses to operate as a single unit separate from the rest of the query, similar to putting parentheses around an expression in a mathematical equation or logic statement. When you group clauses, the And or Or for the first clause in the group applies to the whole group.

As the following table shows, the grouped clauses are translated to the corresponding logical expression. The first expression returns 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 add, remove, group, or ungroup query clauses

1. Add a clause in one of the following ways:

   1. To add the clause at the end of your filter criteria, choose Click here to add a new clause.

   2. Or, to insert a clause, choose the cell in the first column where you want to insert the clause to highlight the row, open the shortcut menu, and then choose Insert Clause.

      A new query clause row is added above where the pointer was.

   3. If you want the clause to be treated as an Or clause, choose the down-arrow button next to And, and then choose Or.

      Choose And if the clause and the previous clause must both be true to match a result. Choose Or if either this clause or the previous clause must be true to match a result.

   4. Specify the values for Field, Operator, and Value.

      Query Column	Usage
      Field	Specify a field for the type of work items that you want to find. The set of work items is filtered based on the Operator and the Values defined for the field. Press ALT+DOWN ARROW or type the field name that you want to select.
      Operator	Specify how the query compares the value found in the specified field in a record. Examples of operator choices are = (equal), <> (not equal to), > (greater than), < (less than), >= (greater than or equal to), <= (less than or equal to), Contains, Does Not Contain, In, and, Was Ever.
      Value	Specify the value that you want to find in the selected field. If there is a list of values from which to select, click the arrow to select the value that you want. You can specify a query variable to dynamically add values to your query. If there is a list of values from which to select, click the arrow to select the one that you want. If there are several values that you want to filter, use the In operator to specify a comma-delimited list of values. To specify a dynamic value, specify a valid query variable.

      For more information, see Query Fields, Operators, Values, and Variables.

2. To delete a query clause, open the shortcut menu for the clause, and then choose Delete Clauses.

3. Group work item query clauses by following these steps:

   1. In your query, select the query clauses that you want to combine into a group by choosing the leftmost cell in the rows. Press CTRL and click to select multiple rows.

   2. Open the shortcut menu for the selected clauses, and then choose Group Clauses.

      A bracket appears in the left margin of the query that shows that the clauses are grouped.

4. Ungroup work item query clauses by following these steps:

   1. In your query, select the whole grouped query clauses that you want to ungroup by clicking the leftmost cell in the rows. Press CTRL and click to select multiple rows.

   2. Open the shortcut menu for the group, and then choose Ungroup Clauses.

      The bracket is removed from the left margin of the query and the clauses are ungrouped.

      Note

      If Ungroup Clauses is unavailable, you have not selected all the clauses in the query grouping. Select all the clauses and try again.

Back to top

5. Run or cancel a query and check results

You can run a work item query to search for the work items in your team project that matches your query criteria. If you change work items that change the results of a query, you can rerun the query to update your results.

1. On the query toolbar, choose Run.

   Note

   You can add any field defined for the work items being searched to control how the query results are displayed and sorted. For more information, see Add, Remove, Reorder, and Sort Columns.

2. To cancel your query search, choose Stop Query, or, on the Team menu, choose Stop Refresh.

3. Review your query results. If the list of work items does not match your expected search criteria, review and modify the filter criteria as needed.

Back to top

6. Adjust your query filter criteria

• If your query results do not return your expected set of work items, perform the following checks:

  • Check each clause to make sure that it is defined as you intended.

  • Check the 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.

  • Check 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 as described in Query Fields, Operators, Values, and Variables. Determine if you want to modify a query clause to use a different field, operator, or value.

Back to top

See Also

Tasks

Work with a flat list (default) query

Work with linked hierarchies (Tree of Work Items)

Concepts

Query Fields, Operators, Values, and Variables

Example Work Item Queries

Query for Bugs, Tasks, or Other Work Items

Other Resources

Work with linked dependencies (Direct Links)