Query fields, operators, values, and variables

Article
07/29/2015

You find and create lists of work items by creating work item queries. By defining one or more clauses, you filter from all work items within a team project or team project collection to return the set of work items that interest you. For each clause, you 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 Query for work items. For information about how to navigate within the query editor or query view using keyboard shortcuts, see Keyboard shortcuts for working in Team Web Access and Team Explorer.

In this topic

And/Or
Query Fields and Values
Query Operators
Query Variables
Full-Text and partial word searches
Query indexed fields

Checklist for how to define a query clause:

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

For more information, see Query Fields and Values.
In the same row, under the Operator column heading, choose the down arrow to display the list of available operators, and choose an item in the list.

For more information, see Operators.
In the same row, under the Value column heading, either type a value, or choose the down arrow, and choose an item in the list.
For more information about how to use variables to specify the current team project, user, or date, see Variables.
To add a clause, choose Click here to add a new clause or Add a new clause.

You can add a clause to the end of the query, insert a clause after an existing clause (), and remove (), group (), and ungroup () clauses as needed.

And/Or

You specify And or Or to create logical expressions of your query clauses. Specify And to find work items that meet the criteria in both the current clause and the previous clause. Specify Or to find work items that meet the criterion in either the current clause or the previous clause.

You can add one new clause for each work item field in order to refine your search criteria, so that it returns 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.

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 example shows, the grouped clauses are translated to the corresponding logical expression. The first expression returns work items that are priority 1, as well as all active bugs of any priority. The second expression returns all active priority 1 work items, plus 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)

For more information, see Specify query filter criteria [redirected].

Query Fields and Values

The value you specify for a field must conform to the data type for that field. The following table lists the supported data types:

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/2012.
Double	A real number, such as 0.2 or 3.5.
GUID	A character string that represents a unique ID.
History	Custom formatted field used to track historical information. This data type is only used to support the History field. This field is automatically indexed for full-text search when full-text search is available. See Full-Text and partial word searches described later in this topic.
HTML	Text strings that support formatted descriptions, such as the Description or Repro Steps fields. These fields are automatically indexed for full-text search when full-text search is available. See Full-Text and partial word searches described later in this topic. Note When you upgrade Team Foundation Server, the Description field is changed from a field type of PlainText to HTML. Using the witadmin changefield command you can revert the data type for this field as needed. See Manage work item fields [witadmin].
Integer	A 32-bit integer that is signed, such as 0, 1, 2, 34.
PlainText	Text strings that support long descriptions, such as the Application Start Information field. These fields are automatically indexed for full-text search, when full-text search is available. See Full-Text and partial word searches described later in this topic.
String	Short text string that can contain up to 255 Unicode characters.
TreePath	A branching tree structure, such as an Area Path or Iteration path. You must choose an item in a list of valid values. You can find work items that equal or are under a tree structure. For more information, see Add and modify area and iteration paths.

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 Work item field reference for Visual Studio ALM.

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, which includes Double, GUID, Integer, and String, DateTime, and TreePath
<>	Does not match the value in the clause.	Number, String, DateTime, and TreePath
>	Is larger than the value in the clause.	Number, String, and DateTime
<	Is less than the value in the clause.	Number, String, and DateTime
>=	Is larger than or equal to the value in the clause.	Number, String, and DateTime
<=	Is less than or equal to the value in the clause.	Number, String, and DateTime
=[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 an exact or partial match of the text string within the field you selected for filtering.	String
Does Not Contain	Does not contain an exact or partial match of the text string within the field you selected for filtering.	String
Contains Words	Contains the exact text string or words within the field you selected for filtering. You can also enter partial words or phrases that contain the wildcard character, *. For restrictions, see Full-text searches for server and collation requirements.	Long-text fields that are indexed for full-text search, which correspond to all PlainText and HTML fields and Title.
Does Not Contain Words	Does not contain the exact text string or words within the field you selected for filtering.	Text fields that are indexed for full text search.
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 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, String, DateTime, TreePath
In Group	Matches a value that is a member of the group in the clause. Groups correspond to the name of a category or a TFS group. For example, you can create a query to find all work items that are assigned to members of the Contributors group or to a team. Team groups are created when you create a team. The name of team groups follows the pattern [Team Project Name]\ Team Name. You can’t specify a security or email distribution group as a value. For worked examples, see Example queries.	String that matches the name of a user group or category group in Team Foundation Server. Note 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 Use categories to group work item types.
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 in Team Foundation Server or a category group defined for a team project. Note 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 Use categories to group work item types.
Was Ever	Matches the value in the clause at any previous point.	String, DateTime
Under	Matches the value in the clause or is contained under the node in the clause.	TreePath
Not Under	Does not match the value in the clause and is not contained under the node in the clause.	TreePath

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.

Full-text and partial word searches

Specify Contains or Does Not Contain to search against exact or partial matches of a word or phrase. Specify Contains Words or Does Not Contain Words to search against an exact phrase or to use the wildcard character, *. These operators use the full-text search index. You can only use the wildcard character at the end of a partial word or phrase.

For examples, see Example work item queries and Query for work items using the History field.

Note

Not all deployments support full-text searches. For example, SQL Express and SQL Azure, which support Visual Studio Online, do not support full-text search. In these instances, you will only see the Contains and Does not Contain operators.

Contains Words and Does Not Contain Words filter items based on the full-text search index created for long-text fields. Team Foundation automatically indexes all long-text fields with a data type of PlainText and HTML and the Title field for full-text search. The index and operators are only available when the SQL Server that supports Team Foundation Server supports full-text search.

Full-text searches require a SQL collation that corresponds to a language which has a word breaker registered with SQL Server. If the collation settings for the team project collection database used for your Team Foundation Server instance do not correspond to a supported language, your search results may not match your expectations. In these cases, you might try using the Contains or Does Not Contain operators.

For more information, see Full-Text Search Queries and Collation Settings.

Query indexed fields

In addition to the full-text search index, a query index is created. It is based on those fields that have indexing enabled. The query index improves the response time when you run queries that include indexed fields.

By default, the following fields are indexed: Assigned To, Created Date, Changed By, State, Reason, Area ID, Iteration ID, and Work Item Type. If there are other fields that your team frequently uses in their queries, you can add them to the query index.

You use the witadmin indexfield command to enable or disable indexing for a field. See Manage work item fields [witadmin].

Partager via