Query fields, operators, and macros

Last Update: 4/4/2017

Team Services | TFS 2017 | TFS 2015 | TFS 2013

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 assigned to you by specifying the Assigned To field, the equals (=) operator, and the as @Me variable which represents your user account.

Sample query clause

And/Or Field Operator Value

And

Assigned To

=

@Me

For more general information about queries, see Use the query editor to list and manage queries. For information about how to navigate within the query editor or query view using keyboard shortcuts, see Keyboard shortcuts.

Checklist for how to define a query clause:

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

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

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

  4. 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 Use the query editor to list and manage queries.

Query field data types 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

Description

Boolean

Specifies a field that takes on a True/False value.

Feature availability: The Boolean data type field is only supported for Team Services and TFS 2017 and later versions.

DateTime

A Coordinated Universal Time (UTC) moment in time. You can specify a variable, such as @Today</strong> or @Today-1</strong>, or a value, such as 1/1/2012. For query examples, see Query by date or@CurrentIteration.

Double

A real number, such as 0.2 or 3.5. For query examples, see Query by numeric fields.

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. For query examples, see History and auditing.

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. To query rich-text fields, see Query by titles, IDs, and rich-text fields.

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. To query plain-text fields, see Query by titles, IDs, and rich-text fields.

String

Short text string that can contain up to 255 Unicode characters. String text fields are often used to support pick lists or drop-down menus.

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.

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 Create managed 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. The operator cannot be used to query Azure Active Directory groups.

For information about category groups, see Use categories to group work item types. For more information about Azure Active Directory and Team Services, see Access with Azure Active Directory groups.

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. The operator cannot be used to query Azure Active Directory groups.

For more information about Azure Active Directory and Team Services, see Access with Azure Active Directory groups.

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 macros or variables

You can use the macros described in the following table to filter your queries based on specific fields.

Macro

Description

[Any] Use in conjuction with the Work Item Type field to search across all work item types. For example, Work Item Type=[Any] won't place any filters based on the work item type.
@Me Use in conjunction with an identity or user account field to automatically search for items associated with your user or account name. For example, you can find work items that you opened with the clause Created By=@Me. For additional examples, see Query by assignment, workflow or Kanban board changes.
@CurrentIteration Use in conjuction with the Iteration Path field to automatically filter for work items assigned to the current sprint based on the current team focus or context. For specific examples, see Query by date or current iteration.
Feature availability: The @CurrentIteration macro is supported for Team Services and TFS 2015 and later versions. The macro only works when run from the web portal.
@Project Use in conjuction with the Team Project field to filter for work items in the current team project. For example, you can find all the work items in the current team project with the clause Team Project=@Project.
Feature availability: For Team Services and TFS 2015.1 and later versions, the system automatically defaults to filtering based on the current team project. To learn more, see Query across team projects.
@Today Use with a DateTime field to filter for work items that relate to the current date or to an earlier date. You can also modify the @Today macro by subtracting days. For example, you can find all items created in the last week with the clause Created Date=@Today-7. For additional examples, see Query by date or current iteration.

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 Team Services, 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.

Switch team project or team focus

Several features depend on the team project or team that you have selected. For example, dashboards, backlogs, and board views will change depending on the context selected.

For example, when you add a work item, the system references the default area and iteration paths defined for the team context. Work items you add from the team dashboard (new work item widget) and queries page are assigned the team default iteration. Work items you add from a team backlog or board, are assigned the team default backlog iteration. To change team defaults, see Set team defaults.

You navigate to your team context from the top navigation bar. The method changes slightly depending on the platform/version you work from.

NOTE

Feature availability: The Account Landing Page feature is in preview mode for Team Services, and enabled for all users from web portal for TFS 2017.1 and later versions. To learn more about this feature, see Work effectively from your account hub. To enable or disable the feature, see Enable preview features.

You can switch your team focus to a team project or team you've recently viewed from the team project/team drop-down menu. If you don't see the team or team project you want, click Browse… to browse all team projects and teams. To access your account hub, click the Team Services icon Team Services icon. If you haven't yet enabled the Account Landing Page, you'll be taken to the account home page.

To go directly to the project vision and status page, choose the project home icon from the drop-down menu, for example, project home icon.

Choose another team from the team project menu

To switch your team focus to a team project or team you've recently viewed, hover over the Team Services icon Team Services icon and choose from the drop-down menu of options. If you don't see the team or team project you want, choose Browse… to browse all team projects and teams. Your selection will open the project vision and status page for the team project.

To access your account hub, click the Team Services icon Team Services icon. If you haven't yet enabled the Account Landing Page, you'll be taken to the account home page.

To go directly to the project vision and status page, choose the project home icon from the drop-down menu, for example, project home icon.

Choose another team from the team project menu

Open the team project/team drop-down menu and select the team project/team that you've recently visited. If you don't see the team or team project you want, choose Browse all to browse all team projects and teams.

Choose another team from the team project menu

Open the team project/team drop-down menu and select the team project/team that you've recently visited. If you don't see the team or team project you want, choose Browse all to browse all team projects and teams.

Choose another team from the team project menu