Specify Query Criteria

You can specify criteria for your query to find work items. By using different criteria, you can check what is assigned to you, identify your active tasks, or display a list of features that are assigned to you or your team.

All work item queries consist of one or more clauses, and each clause includes a field, an operator, and a value. You can filter the set of work items to meet your needs by adding, modifying, and grouping clauses and fields in queries that you create.

Topic Contents

To specify the criteria for a query, complete the following procedures until a list of work items appears in Query Results:

1. Select the Query Type

2. Specify the Top-Level Criteria

3. Add, Remove, Group, or Ungroup Clauses

4. Run a Query

5. Adjust the Criteria

For information about how to filter your criteria based on a date value or membership in 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 team query, you must be a member of the Project Administrators group. For more information, see the following page: Team Foundation Server Permissions.

Select the Query Type

To select your query type

• Open your team project, right-click the Work Items, My Queries, or Team Queries node, and then click New Query.

  A new query opens.

  Note

  The Team Foundation Server plug-in for Eclipse supports only flat-list queries. You must use a different client for Team Foundation if you want to create or modify a multi-tiered query.

Specify the Top-Level Criteria

The top-level criteria limit the query results by team project and type of work item.

Note

By default, a query returns all work items (Work Item Type=[Any] and State=[Any]) that are assigned to you (Assigned To=@Me) in the current team project (Team Project=@Project).

If you work on several team projects, you may want to search them all by using a single query.

To specify the top level filter criteria

1. Specify the team project or projects that contain the work items that you want to find.

   • If you want to find work items in the current team project, keep Team Project=@Project.

   • If you want to find work items in another team project, type the name of the project in the Value column for the Team Project field.

   • If you want to find work items in several team projects, specify the values in the following table:

     And/Or	Field	Operator	Value
     	Team Project	In	FirstTeamProjectName, SecondTeamProjectName, ...

     Separate the names of team projects by using commas (,).

2. Specify the type of work items that you want to find.

   • If you want to find all types of work items, keep Work Item Type=[Any].

   • If you want to find a single type of work item, click the Value column for the Work Item Type field, and then click the type of work item that you want to find.

   • If you want to find several types of work items, specify the values in the following table:

     And/Or	Field	Operator	Value
     And	Work Item Type	In	FirstWorkItemType, SecondWorkItemType, ...

     Separate the names of work item types by using commas (,).

   • If you want to find all types of work items that belong to a named category, specify the values in the following table:

     And/Or	Field	Operator	Value
     And	Work Item Type	In Group	NameOfWorkItemTypeCategory

     For information about how to define categories of work item types, see the following page: Customizing Categories for Work Item Types.

     For more information about ways to specify top-level criteria, see Query Operators.

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

   You can also right-click in the query window, and then click Run Query.

4. On the File menu, click Save or Save As.

   You can also press CTRL+S to save.

Add, Remove, Group, or Ungroup Query Clauses

You can add one clause for each work item field to refine your query results. If you do not receive the results that you expect from your query, you can add, remove, group, or ungroup clauses to refine your results. For information about the elements in a clause, see Query Fields, Operators, Values, and Variables (Team Explorer Everywhere).

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

You can group query clauses to operate as a single unit that is separate from the rest of the query. This approach resembles 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.

To add, remove, group, or ungroup query clauses

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

   1. To add the clause after the last clause for your query, click Click * in the left-most column.

   2. To insert a clause between two clauses, right-click just under where you want to insert the clause, and then click Insert Clause.

      A clause row appears above where the pointer was.

   3. To specify that the clause should be treated as an Or clause, click in the And/Or column, and then click Or in the list.

      Click And if results must match both this clause and the previous clause. Click Or if results must match either this clause or the previous clause but not both.

   4. Specify the values for Field, Operator, and Value, as the following table shows:

      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 that are defined for the field. Press ALT+DOWN ARROW or type the field name that you want to specify.
      Operator	Specify how the query compares the value in the specified field in a record. Examples of operator choices are = (equals), <> (does not equal), > (more than), < (less than), >= (more 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 you can specify a value from a list, click the arrow to specify the one that you want. If you want to filter by several values, 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 (Team Explorer Everywhere).

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. To group clauses, follow these steps:

   1. In your query, specify the query clauses that you want to group by holding down CTRL and clicking the leftmost cell in each row.

   2. Right-click the highlighted clauses, and then click Group Clauses.

   3. A bracket appears in the left margin of the And/Or column to show that the clauses are grouped.

4. To ungroup clauses, follow these steps:

   1. In your query, highlight all clauses in the group by holding down CTRL and clicking the leftmost cell in each row.

   2. Right-click the group, and then click Ungroup Clauses.

      The bracket disappears from the left margin of the query, and the clauses are ungrouped.

      Note

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

Run a Query

If a work item changes so that it either matches or no longer matches the criteria, you can rerun the query to update your results.

To run a query

1. On the toolbar, click Run Query.

   You can also right-click in the query and then click Run Query.

   Note

   You can change which columns appears in your results and how they are sorted by adding any field that has been defined for the work items that you are searching. For more information, see Add, Remove, Reorder, and Sort Columns (Team Explorer Everywhere).

2. Review your query results. If they do not match your search criteria, review and modify the criteria.

   Note

   You cannot cancel a running query in this release of the Team Foundation Server plug-in for Eclipse.

Adjust the Criteria

If the results of your query do not match your expectations, follow the steps in this procedure.

To adjust your criteria

1. Verify whether each clause is defined as you intended.

2. Verify the And/Or assignments of each clause.

   If your results contain more work items than you expected, an Or clause might be present instead of an And clause.

3. Check the grouping of the clauses.

4. If the query returns too many results, add clauses to refine your criteria.

Specify Date-Time Criteria

You can search for work items that were changed either on a particular date or during a particular range of dates. If you limit the scope of your query, you can boost performance by returning only those results that fit the date or date range that you want to include.

To search for work items that were modified today

1. Select a value in the Field column that is a Date data type.

   Note

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

2. In the Operator column, click = (Equals).

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

   Note

   You can modify this variable to search for work items that were changed within a particular number of days before today. For example, you can find all items that were created in the last week if you set the Field column to Activated Date, the Operator column to >=, and the Value column to @Today - 7.

4. On the toolbar, click Run Query, and review your query results.

   You can also right-click in the query definition and then click Run Query.

To search for work items that were modified on a specific date

1. Select a value in the Field column that is a Date data type to add or modify a query clause.

2. In the Operator column, click = (Equals).

3. In the Value column, type the date on which items must have been modified.

4. On the toolbar, click Run Query, and review your query results.

   You can also right-click in the query definition and then click Run Query.

To search for work items that were modified during a range of dates

1. Select a value in the Field column that is a Date data type to add or modify a query clause.

2. In the Operator column, click > (Greater Than) or click >= (Greater Than or Equal To) to specify the earliest date in the range.

   Specify >= (Greater Than or Equal To) if you want to find items that were modified on the earliest date in the range.

3. In the Value column, type the earliest date in the range.

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

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

6. In the Operator column, click < (Less Than) or click <= (Less Than or Equal To) to specify the most recent date in the range.

   Specify <= (Less Than or Equal To) if you want to find items that were modified on the most recent date in the range.

7. In the Value column, specify the most recent date in the range.

8. Group the two clauses that you just created.

9. On the toolbar, click Run Query, and review your query results.

   You can also right-click in the query definition and then click Run Query.

Specify a Filter Based on Membership in a Group

You can use the In Group or Not In Group operators to specify criteria based on several values that are members of a group or that are not members of a group. Examples of groups are distribution groups that are defined in Team Foundation Server, a category of work item types, or all active bugs that are assigned to your reports.

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

1. You can search for work items that meet the following criteria:

   • To find work items that are assigned to someone who belongs to the Project Administrators group, add the clause that the following table shows:

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

   • To find work items that are active and assigned to someone who reports to you, add the clauses that the following table shows:

     And/Or	Field	Operator	Value
     And	State	=	Active
     And	Assigned To	In Group	MyDirectReportsDistributionGroup

2. On the toolbar, click Run Query, and review your query results.

   You can also right-click in the query definition and then click Run Query.

See Also

Tasks

Add, Remove, Reorder, and Sort Columns (Team Explorer Everywhere)

Save, Copy, Rename, and Delete Work Item Queries (Team Explorer Everywhere)

List Work Items (Default Flat List) (Team Explorer Everywhere)

Other Resources

Query Fields, Operators, Values, and Variables (Team Explorer Everywhere)

Finding Bugs, Tasks, and Other Work Items (Team Explorer Everywhere)