Operators (Work Item Query Reference)
Queries use logical expressions to qualify result sets. These logical expressions are formed by one or more conjoined operations.
Working with Operators
Some simple query operations are listed below.
WHERE [System.AssignedTo] = 'joselugo'
WHERE [Adatum.CustomMethodology.Severity] >= 2
The table below summarizes all the supported operators for different field types.
Field Type |
Supported Operators |
|---|---|
=, <>, >, <, >=, <= |
|
=, <>, >, <, >=, <= |
|
=, <>, >, <, >=, <=, Contains |
|
Contains |
|
Under, =, <> |
The =, <>, >, <, >=, and <= operators work as expected. For instance, System.ID > 100 queries for all work items with ID greater than 100. System.ChangedDate > '1/1/06 12:00:00' queries for all work items changed after noon of January 1, 2006.
Beyond these basic operators, there are some behaviors and operators specific to certain field types.
DateTime
You must quote (single or double quotes are supported) DateTime literals used in comparisons. They must be in the .NET DateTime format of the local client computer running the query. Unless a time zone is specified, DateTime literals are in the time zone of the local computer.
WHERE [Adatum.Lite.ResolvedDate] >= '1/8/06 GMT' and [Resolved Date/Time] < '1/9/06 GMT'
WHERE [Resolved Date] >= '1/8/06 14:30:01'
When the time is omitted in a DateTime literal and the dayPrecision parameter equals false, the time is assumed to be zero (midnight). The default setting for the dayPrecision parameter is false.
When the time is omitted in a DateTime literal and the dayPrecision parameter equals true, expressions will be interpreted as follows.
WIQL |
Interpretation WIQL |
|
|
|
|
|
|
String and PlainText
You must quote string literals (single or double quotes are supported) in a comparison with a string or plain text field. String literals support all Unicode characters.
WHERE [Adatum.Lite.Blocking] = 'Not Blocking'
WHERE [Adatum.Lite.Blocking] <> 'Blocked'
You can use the contains operator to search for a substring anywhere in the field value.
WHERE [System.Description] contains 'WIQL'
Area and Iteration
You can use the under operator for the Area and Iteration Path fields. under evaluates whether a value is within the sub-tree of a specific classification node. For instance, the expression below would evaluate to true if the Area Path were 'MyProject\Server\Administration', 'MyProject\Server\Administration\Feature 1', 'MyProject\Server\Administration\Feature 2\SubFeature 5', or any other node within the sub-tree.
WHERE [System.AreaPath] under 'MyProject\Server\Administration'
Modifiers and Special Operators
You can use some modifiers and special operators in a query expression.
Use the in operator to evaluate whether a field value is equal to any of a set of values. This operator is supported for the String, Integer, Double, and DateTime field types. See the following example along with its semantic equivalent.
WHERE [System.CreatedBy] in ('joselugo', 'jeffhay', 'linaabola')
WHERE [System.CreatedBy] = 'joselugo' OR [System.CreatedBy] = 'jeffhay' OR [System.CreatedBy] = 'linaabola'
The ever operator is used to evaluate whether a field value equals or has ever equaled a particular value throughout all past revisions of work items. The String, Integer, Double, and DateTime field types support this operator. There are alternate syntaxes for the ever operator. For example, the snippets below query whether all work items were ever assigned to 'joselugo'.
WHERE ever ([Assigned To] = ‘joselugo')
WHERE [Assigned To] ever ‘joselugo'