Share this page
query Clause: Restrict response by field values
Description
Limit the data returned by a query according to field values.
Applies To
GET on collections.
Remarks
To restrict a request to instances that meet criteria, use a query clause.
Query Syntax
The elements of a query clause are:
- Comparison operators
- Logical operators
- Literals
- Pairs of parenthesis
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')
Literals
| 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 |
Parenthesis
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.
Examples
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')"
