ALM 12.5x REST API Reference
query Clause: Restrict response by field values


Limit the data returned by a query according to field values.

Applies To

GET on collections.


To restrict a request to instances that meet criteria, use a query clause.

Query Syntax

The elements of a query clause are:

A query clause cannot contain a reference to another type of resource. You can filter only on field values of this resource.  

Comparison Operators

Operator Functionality Example
= Equal to id=1001
< Smaller Than id<1001
> Greater Than id>1001
<= Smaller Than or Equal to id<=1001
>= Greater Than or Equal to id>=1001

Logical Operators

Operator Functionality Example
; and status='open';(user-03<10)
|| or (user-03<10||user-03>20)
! not !(user-03=10)

Limitation: An OR expression on two difference fields cannot be ANDed with another expression. For example, this query fails:

(id > 200 || status < '5-Ready') ; (owner = 'sa')

The OR expression between the id field and the status field, (id > 200 || status < '5-Ready'), cannot be ANDed with any other expression.

The query can be rewritten as follows to avoid the limitation:

(id > 200 ; owner = 'sa') || (status < '5-Ready' ; owner = 'sa')


Literal Comment Example
String Literals Strings that represent the value of an expression. String values in queries are passed in single quotes: 'myString'.
Literals can contain the asterisk wild card (*).
If a string contains a single quote, escape it with a backslash. For example, pass d'Artagnan as 'd\'Artagnan'.
status = 'Ready'
owner = 'alon*'
Numbers The numeric value of an expression. id > 1
true Value of Boolean expression. has-attachment = true
false Value of Boolean expression. has-attachment = false
null Specifies that the field has no value. release-id = null


Expressions in parenthesis are evaluated and the results are used in the expression that contains the parenthetical expression. Parenthetical expressions can be nested. For example, in the following expression, the OR expression on values of severity is evaluated. Then, the result of the OR expression is evaluated in the AND expression with detected-by. The result of the AND expression is ORed with the owner condition.


defects?fields=id,name,description,status&query="status = 'New' || status = 'Open'"
defects?fields=id,name,severity,detected-by&query="id >1" ; "(status = 'New' || status = 'Open')"

See Also