Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020
This article describes field data types, query operators, and query macros you use in the Query Editor. Some types, operators, and macros apply only to specific Azure DevOps versions.
For quick examples and editor tasks, see Query quick reference and Manage and organize queries.
Prerequisites
| Category | Requirements |
|---|---|
| Access levels | - To view and run shared queries: Project member. - To add and save a shared query: At least Basic access. |
| Permissions | Contribute permission set to Allow for the folder that you want to add a query to. By default, the Contributors group doesn't have this permission. |
Note
Users with Stakeholder access for a public project have full access to query features just like users with Basic access. For more information, see Stakeholder access quick reference.
| Category | Requirements |
|---|---|
| Access levels | - To view and run shared queries: Project member. - To add and save a shared query: At least Basic access. |
| Permissions | Contribute permission set to Allow for the folder that you want to add a query to. By default, the Contributors group doesn't have this permission. |
Query field data types and values
You must specify a value that matches the data type for a field. The table below lists supported data types:
Note
For Azure Boards (cloud), the data type matches the field shown on the Process > Fields page. For on-premises deployments, the data type corresponds to the type attribute on a FIELD definition. See Work item fields and field attributes for details.
Data type
Description
Boolean
Stores a True/False value.
DateTime or Date/Time
Use a date variable (for example, @Today or @Today-1) or an explicit date like 01/01/2025. Enter dates in the pattern set in your profile. For query examples, see Query by date or @CurrentIteration.
For WIQL queries, you can also specify dates in UTC. See Syntax for the Work Item Query Language (WIQL).
Double or Decimal
Stores a real number, such as 0.2 or 3.5. See Query by numeric fields for examples.
GUID
Stores a unique identifier string.
History
Custom formatted field used for historical information (the History field). When full-text search is available, this field is indexed for full-text queries. See History and auditing.
HTML
Stores formatted text (for example, Description or Repro Steps). When full-text search is available, these fields are indexed. To query rich-text fields, see Query by titles, IDs, and rich-text fields.
Identity
Stores a short text string that identifies a user identity.
Integer
Stores a signed 32-bit integer (for example, 0, 1, 2, 34).
PlainText or Text field (multi-line)
Stores long text values (for example, Application Start Information). These fields index for full-text search when supported. See Query by titles, IDs, and rich-text fields.
picklistDouble
Custom field that holds a pick list of Decimal values.
picklistInteger
Custom field that holds a pick list of Integer values.
picklistString
Custom field that holds a pick list of short text values (255 characters or less).
String or Text field (single line)
Stores short text up to 255 Unicode characters. Teams often use these fields for picklists or drop-down menus.
TreePath
Represents a branching tree (for example, Area Path or Iteration Path). Choose a valid node value. You can filter for equality, inequality, "Under" / "Not Under," or use the In / Not In operators to specify multiple values. Define tree structures for a project—area paths and iteration paths—and select the nodes to associate with teams.
For query examples, see Query by area or iteration path and Query by date or current iteration.
Note
The picklist... types only apply to custom fields defined for an inherited process.
Date and time pattern
The date and time pattern you enter for DateTime fields should match that which you select through your profile. To view or change your selection, see Set user preferences.
Query operators
Use operators to define how a clause value must relate to a work item's field value. For field data types, see Work item field reference. For help building queries, see Define a query.
Query operator
When the operator returns matching work items
Applicable data types
=
Matches the clause value.
Number (Double/Decimal/GUID/Integer), String, DateTime, TreePath
<>
Doesn't match the clause value.
Number, String, DateTime, TreePath
>
Is greater than the clause value.
Number, String, DateTime
<
Is less than the clause value.
Number, String, DateTime
>=
Is greater than or equal to the clause value.
Number, String, DateTime
<=
Is less than or equal to the clause value.
Number, String, DateTime
=[Field]
Matches the value in another specified field (must be the same data type).
Name of a field of the same data type (Boolean fields compare equality to other fields).
<>[Field]
Doesn't match the value in another specified field.
Name of a field of the same data type.
>[Field]
Is greater than the value in another specified field.
Name of a field of the same data type.
<[Field]
Is less than the value in another specified field.
Name of a field of the same data type.
>=[Field]
Is greater than or equal to the value in another specified field.
Name of a field of the same data type.
<=[Field]
Is less than or equal to the value in another specified field.
Name of a field of the same data type.
Contains
Contains an exact or partial text match.
String
Does Not Contain
Doesn't contain an exact or partial text match.
String
Contains Words
Matches an exact phrase or words (supports trailing wildcard *). Limit: 100 characters. This operator uses full-text indexing; see the Full-text section in this article for server and collation requirements.
Long-text fields indexed for full-text search (PlainText, HTML, History, and Title).
Does Not Contain Words
Excludes items that contain the specified phrase or words. Limit: 100 characters. Use with Contains Words in companion clauses to include or exclude keywords.
Text fields indexed for full-text search.
In
Matches any value in a delimited set (use your OS regional list separator, typically a comma).
Number, String, DateTime, TreePath
Is Empty
Matches items where an HTML field contains no content (no value specified). Supported for Azure Boards and Azure DevOps Server.
HTML
Is Not Empty
Matches items where an HTML field contains content. Supported for Azure Boards and Azure DevOps Server.
HTML
Not In
Excludes values in a delimited set (use the regional list separator). Supported for Azure Boards and Azure DevOps Server.
Number, String, DateTime, TreePath
In Group
Matches values that are members of a named group (team, security group, or category). For example, use the Contributors group or a team group named in the pattern [Project Name]\Team Name. See Query by assignment or workflow changes for examples.
String (matches group or team name) or Work Item Type
Note
Use In Group only with String-type fields or Work Item Type. You can use Microsoft Entra ID groups when your account uses Microsoft Entra ID, or Active Directory groups for on-premises. :::column-end:::
Not in Group
Excludes members of a named group.
String that matches a user group or project category.
Not Under
Excludes items equal to or contained under the specified tree node.
TreePath
Under
Matches items equal to or contained under the specified tree node.
TreePath
Was Ever
Matches a value that a field held at any previous time.
String, DateTime
Note
The Query Editor doesn't currently support Was Ever on date fields; use direct WIQL for those cases.
:::column-end:::
Tip
You can construct WIQL queries that use operators (for example, Was Ever) against other data types such as Iteration Path. See List work items moved out of a sprint for an example.
Query macros and variables
Use the following macros to filter queries dynamically.
Note
The following macros are only supported from the web portal: @CurrentIteration, @CurrentIteration +/- n, @Follows, @MyRecentActivity, @RecentMentions, @RecentProjectActivity, and @TeamAreas. Queries that contain these macros won't work when opened in Visual Studio/Team Explorer, Microsoft Excel, or Microsoft Project.
Macro
Description
[Any]
Use with Work Item Type or State to search across all types or states. For example, Work Item Type=[Any] removes type-based filtering.
@CurrentIteration
Use with Iteration Path to filter for work items in the current sprint based on the current team context. See Query by date or current iteration for examples. @CurrentIteration works only when run from the web portal (not in REST APIs or some copy/clone operations).
@CurrentIteration +/- n
Use with Iteration Path to include sprints relative to the current iteration (for example, @CurrentIteration-1 or @CurrentIteration+2). Supported in the web portal for Azure Boards and Azure DevOps Server.
@Follows
Use with ID and the In operator to list work items you follow in the project. See Follow a work item or pull request. This macro works only from the web portal.
@Me
Use with identity fields to filter for items linked to your account (for example, Created By=@Me). See Query by assignment, workflow, or board changes.
@MyRecentActivity
Use with ID and In to list work items you viewed or updated in the last ~30 days. See the Work Items page My activity pivot for the same list.
@Project
Use with Team Project to filter for work items in the current project (for example, Team Project=@Project). See Query across projects.
@RecentMentions
Use with ID and In to list work items where you're mentioned in Discussions. See the Work Items page Mentioned pivot.
@RecentProjectActivity
Use with ID and In to list recently updated work items across the project. The macro returns up to 5,000 items; the actual window depends on project activity.
@StartOfDay
Use with DateTime fields to filter relative to today (for example, Closed Date>=@StartOfDay-7).
@StartOfMonth
Use with DateTime fields to filter relative to the start of the month (for example, Created Date>=@StartOfMonth-3).
@StartOfWeek
Use with DateTime fields to filter relative to the start of the week (for example, Changed Date>=@StartOfWeek-2).
@StartOfYear
Use with DateTime fields to filter relative to the year's start (for example, Target Date>=@StartOfYear).
@TeamAreas
Use only with Area Path and the = operator to find items assigned to a team's area paths (for example, Area Path=@TeamAreas [Fabrikam Fiber]\Web). Supported in the web portal for Azure DevOps Server.
@Today
Use with DateTime fields to filter relative to today (for example, Created Date>=@Today-7). See Query by date or current iteration.
Full-text and partial-word searches
Use Contains or Does Not Contain to search exact or partial matches against long-text fields (these operators use the query index). Use Contains Words or Does Not Contain Words to search exact phrases or use a trailing wildcard (*); these operators require the full-text index.
You can use the wildcard only 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 search. For example, SQL Express and some cloud SQL configurations don't support full-text search. In those deployments, only the Contains and Does Not Contain operators are visible.
Azure DevOps Server indexes long-text fields (PlainText and HTML) and the Title field for full-text search when the underlying SQL Server supports full-text indexing.
Full-text search also requires a SQL collation with a registered word breaker for the language you use. If the collection database collation doesn't match a supported language, results might not match expectations; in those cases use Contains or Does Not Contain instead.
For more information, see Full-Text Search Queries and Collation Settings.
Related content
- Use the query quick reference
- Learn about managed queries
- Access the work item field index
- Understand WIQL syntax
REST API
To programmatically interact with queries, see one of these REST API resources: