Specify Query Filter Criteria

You can specify the filter criteria for your query to find work items and more easily select the filtered data that you want to use. By using different filter criteria, you can check what is assigned to you, what your active tasks are, or see a list of features assigned to you or your team.

All work item queries consist of one or more query clauses; each clause includes a field, an operator, and a value. You can add, modify and group clauses and fields in queries that you create by filtering the set of work items to meet your needs.

In this topic

To specify your filter criteria, complete the following procedures until you have the set of work items listed in the Query Results view:

1. Select the Type of Query

2. Specify Top Level Query Filter Criteria

3. Add, Remove, Group, or Ungroup Query Clauses

4. Run or Cancel a Query and Check Query Results

5. Adjust Your Query Filter Criteria

   Note

   The following procedures are written for Team Explorer. The procedures for Team Web Access are similar but may vary slightly in detail.

To filter your criteria based on a date value or a value that belongs to a group, see the following procedures:

• Specify a Filter Based on a Date-Time Value

• Specify a Filter Based on Membership in a Group

Required Permissions

To perform these procedures, you must be a member of the Readers group, or your View work items in this node permission must be set to Allow for each team project in the query. To save a query as a team query, you must be a member of the Project Administrators group. For more information, see Team Foundation Server Permissions.

Select the Query Type

To select your query type in Team Explorer

1. Open your team project, expand the Work Items node, and then select Team Queries or My Queries.

2. On the Team menu, click Add Query. Or, right-click the Work Items, My Queries, or Team Queries node, and then click Add Query.

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

3. 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 of Work Items (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 List Work Items (Default Flat List).

   • 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 View and Modify Work Items in a Direct Links View.

   • 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 View and Modify Work Items in a Tree View.

Back to top

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.

To specify the top level filter criteria

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, click the Value column for the Work Item Type field, and then click 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 work item type groups, see Customizing 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, click Run, and confirm that your query returned the results that you expected.

4. Click Save or Save as. For more information, see Save, Copy, Rename, and Delete Work Item Queries.

Back to top

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.

Query clauses can be grouped 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, click Click here to add a new clause.

   2. Or, to insert a clause, right-click where you want the clause inserted, and click 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, click And, and then click Or.

      Select And if the clause and the previous clause must both be true to match a result. Select 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. Delete a query clause by right-clicking to the left of the clause row that you want to delete, and then click 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 clicking the leftmost cell in the rows. Press CTRL and click to select multiple rows.

   2. Right-click the selected clauses, and then click 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. Right-click the group, and then click 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

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.

To run or cancel a query based on the query filter criteria

1. On the query toolbar, click 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, click Stop Query, or, on the Team menu, click 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

Adjust Your Query Filter Criteria

To adjust your filter criteria

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

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

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

  3. Check the grouping of the query clauses and the And/Or assignments of each grouped clause.

  4. Add more query clauses to refine your query filter criteria.

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

Specify a Filter Based on a Date-Time Value

You can sort for work items by the date on which they were changed or for a specific time period. If you limit the scope of your query, it can help with performance by only returning those results that fit the date range that you want to include.

To find work items based on date-specific filter criteria

1. Search for work items modified today by following these steps:

   1. Select a Field that is a date data type to add or modify a query clause.

      Note

      Most date fields contain the word "date" in the field name.

   2. In the Operator column, select = (Equal).

   3. In the Value column, click the arrow and select @Today for today's date.

      Note

      You can modify this variable to search for the current date minus a number of days. For example, to find all items started in the last week, you would set the Field column to Activated Date, the Operator column to >=, and the Value column to @Today - 7.

   4. Click Run, and check your query results.

2. Search for work items modified on a specific date by following these steps:

   1. Select a Field that is a date data type to add or modify a query clause.

   2. In the Operator column, select = (Equal).

   3. In the Value column, type the date that follows the format accepted by your computer's operating system.

   4. Click Run, and check the query results.

3. Search for work items modified over a range of dates by following these steps:

   1. Select a Field that is a date data type to add or modify a query clause.

   2. In the Operator columnselect either > (Greater Than), if you only want items after the date, or >= (Greater Than or Equal To) if you want items that include the date that you select.

   3. In the Value column, enter the first date in the range of dates that follows the date format accepted by your computer's operating system.

   4. Insert another query clause directly underneath the previous query clause.

   5. In the And/Or assignments column, select And.

   6. In the Operator column,select either < (Less Than) if you only want items before the date, or <= (Less Than or Equal To) if you want items that include the date that you select.

   7. In the Value column, enter the last date in the range of dates following the date format accepted by your computer's operating system.

   8. In the Operator column, select = (Equal).

   9. In the Value column, type the date that follows the format accepted by your computer's operating system.

   10. Select the two date-specific query clauses and group them.

   11. Click Run, and check the query results.

Back to top

Specify a Filter Based on Membership in a Group

You can use the In Group or Not In Group operators to filter a query based on several values that are or are not members of a group. You can specify distribution groups in Team Foundation Server or one or more categories of work item types.

To find work items based on a value that belongs to a group

1. Specify the following types of clauses:

   • Add the following clause to find work items that are assigned to any user who belongs to the Project Administrators group:

     And/Or	Field	Operator	Value
     And	Assigned To	In Group	Project Administrators

   • Add the following clause to find active work items that are of any type of work item in the Test category group:

     And/Or	Field	Operator	Value
     And	State	=	Active
     And	Work Item Type	In Group	Test

   For information about category groups, see Grouping Work Item Types into Categories.

2. Click Run Query, and check the query results.

Back to top

See Also

Tasks

Add, Remove, Reorder, and Sort Columns

Save, Copy, Rename, and Delete Work Item Queries

List Work Items (Default Flat List)

View and Modify Work Items in a Direct Links View

View and Modify Work Items in a Tree View

Concepts

Query Fields, Operators, Values, and Variables

Finding Bugs, Tasks, and Other Work Items