Query Fields, Operators, Values, and Variables

  • Article

When you create a query to search for work items in Visual Studio Team Foundation Server 2010, you can define one or more clauses that identify the set of work items that you want to find. For each clause, you can specify a field, an operator, and a value or variable. For example, you can search for all work items in a particular team project by specifying the Team Project field, the equals (=) operator, and the name of the team project as the value. Instead of specifying a value, you can specify a variable such as @Project, which represents the current team project.

Sample query clause

And/Or

Field

Operator

Value

And

Team Project

=

@Project

For more general information about queries, see Finding Bugs, Tasks, and Other Work Items. For information about how to navigate within the query editor or query view using keyboard shortcuts, see Keyboard Shortcuts for the Query Editor and Query Results View.

In this topic

  • And/Or

  • Query Fields and Values

  • Query Operators

  • Query Variables

Checklist for how to define a query clause:

  1. In the first empty row, click under the Field column heading, click the down arrow to display the list of available fields, and click an item in the list.

    For more information, see Query Fields and Values.

  2. In the same row, click under the Operator column heading, click the down arrow to display the list of available operators, and click an item in the list.

    For more information, see Operators.

  3. In the same row, click under the Value column heading.

  4. Type a value, or click the down arrow, and click an item in the list.

  5. For more information about how to use variables to specify the current team project, user, or date, see Variables.

  6. To add a clause, click Click here to add a new clause.

    You can add a clause to the end of the query, insert a clause after an existing clause (Insert Query Clause), and remove (Delete Query Clause), group (Group Query Clause), and ungroup (Ungroup Query Clause) clauses as needed. You can also copy and paste the contents of a clause to a new location. For more information, see Specify Query Filter Criteria.

And/Or

You can use this column to specify how clauses are tested. You can specify And if you want to find work items that meet the criteria in both this clause and the previous clause. You can specify Or if you want to find work items that meet the criterion in either this clause or the previous clause.

Query Fields and Values

When you specify a value for each field, the value must conform to the data type of that field. All fields in Team Foundation have one of the data types listed in the following table:

Data type

Data stored

DateTime

A Coordinated Universal Time (UTC) moment in time. You can specify a variable, such as @Today or @Today-1, or a value, such as 1/1/2009.

Double

A real number, such as 0.2 or 3.5.

GUID

A character string that represents a unique ID.

HTML

Text strings that support formatted descriptions.

Integer

A 32-bit integer that is signed, such as 0, 1, 2, 34.

PlainText

Text strings that support long descriptions, such as the Description or History fields are defined for a work item. You can find work items based on a phrase or keyword that is contained within a PlainText field.

String

Text string that contains up to 255 Unicode characters.

TreePath

A branching tree structure, such as an Area Path or Iteration path. You must click an item in a list of valid values. You can find work items that equal or are under a tree structure.

Back to top

Query Operators

You can use query operators in the following table to specify how each value in a clause must relate to the corresponding value in a work item. For information about the data type that is assigned to work item fields, see Using System Fields and Fields Defined by the MSF Process Templates.

Query operator

Returns work items if the value in the work item matches the criteria listed

Applicable data types

=

Matches the value in the clause.

Number, Text, Date, Tree

<>

Does not match the value in the clause.

Number, Text, Date, Tree

>

Is larger than the value in the clause.

Number, Text, Date

<

Is less than the value in the clause

Number, Text, Date

>=

Is larger than or equal to the value in the clause.

Number, Text, Date

<=

Is less than or equal to the value in the clause.

Number, Text, Date

=[Field]

Matches the value that is contained in the specified field

Name of a field that is of the same data type as the specified field

<>[Field]

Does not match the value that is contained in the specified field

Name of a field that is of the same data type as the specified field

>[Field]

Is larger than the value that is contained in the specified field

Name of a field that is of the same data type as the specified field

<[Field]

Is less than the value that is contained in the specified field

Name of a field that is of the same data type as the specified field

>=[Field]

Is larger than or equal to the value that is contained in the specified field

Name of a field that is of the same data type as the specified field

<=[Field]

Is less than or equal to the value that is contained in the specified field

Name of a field that is of the same data type as the specified field

Contains

Contains the text value in the clause.

Text

Does Not Contain

Does not contain the text value in the clause.

Text

In

Matches any value in a delimited set. For example, you can find work items whose IDs are 100, 101, and 102 if you specify those values for the ID field.

Important noteImportant
Separate values with the list separator that corresponds to the regional settings that are defined for your client computer. For example, you might use a comma(,).

Number, Text, Date, Tree

In Group

Matches a value that is a member of the group in the clause. You can specify a default, custom, or category group in Team Foundation Server. For example, you can create a query to find all work items that are assigned to members of the Contributors group.

NoteNote
You cannot specify a security or email distribution group as a value.

String that matches the name of a user group or category group in Team Foundation Server.

NoteNote
You can use the In Group operator only with fields that use the String data type or the Work Item Type field.

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

Not in Group

Does not match a value that is a member of the group in the clause.

String that matches the name of a user group or a category group in Team Foundation Server

NoteNote
You can use the Not In Group operator only with fields that use the String data type or the Work Item Type field.

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

Was Ever

Matches the value in the clause at any previous point.

Text, Date

Under

Matches the value in the clause or is contained under the node in the clause.

Tree

Not Under

Does not match the value in the clause and is not contained under the node in the clause.

Tree

Back to top

Query Variables

You can use the variables in the following table to find work items that relate to the current user, the current project, or the current date.

Query variable

Usage

@Me

Use this variable to automatically search for the current user's alias in a field that contains user aliases. For example, you can find work items that you opened if you set the Field column to Activated By, the Operator column to =, and the Value column to @Me.

@Project

Use this variable to search for work items in the current team project. For example, you can find all the work items in the current team project if you set the Field column to Team Project, the Operator column to =, and the Value column to @Project.

@Today

Use this variable to search for work items that relate to the current date or to an earlier date. You can also modify the @Today variable by subtracting days. For example, you can find all items activated in the last week if you set the Field column to Activated Date, the Operator column to >=, and the Value column to @Today - 7.

[Any]

Use this variable to search for work items that relate to any value that is defined for a particular field.

Back to top

See Also

Tasks

Specify Query Filter Criteria

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

Finding Bugs, Tasks, and Other Work Items

Other Resources

Sharing Work Items and Queries with Team Members