Integer

Boolean

DateTime

String

Memo

Reference

EQ

Equal to

id EQ 1001

LT

Less than

id LT 1001

GT

Greater than

id GT 1001

LE

Less than or equal to

id LE 1001

GE

Greater than or equal to

id GE 1001

IN

Exists in a list of values, separated by commas.

The relationship between the items in the list of values is an OR relationship. This means that as long as one of the values match, the operation succeeds.

The list of values can also include:

• The current user ( [current_user] ). This is the currently logged in user that is calling the REST API.

• The current release ( [current_release]). This is the release set as the default in the ALM Octane Settings area.

id IN [current_user], 1001, 1002, 1003

BTW

Exists in a range of values, specified by two numbers separated by three dots ( ...) with a space before the three dots. This is an inclusive range. This is the same as saying greater than or equal to a number and less than or equal to another number.

id BTW 12 ...16 ( )

;

And

||

Or

Not

The negation operator ! is optional. This operator reverses the meaning of the subsequent operand.

()

1

The following statements are equivalent: 

• "(!name EQ ^test^);flag EQ true"

• "!name EQ ^test^;flag EQ true"

!

2

Numeric

Numeric values are placed after the comparison operator.

/<some_entities>?query=”<some_numeric_field_name> GE 35”

id GT 1

Valid values: true or false.

/<some_entities>?query="<some_boolean_field_name> EQ true"

Must be wrapped in carets: ^string^

Escaping of special characters in strings is supported. See Special characters.

If a string contains a single quote, double quote, or a circumflex, escape it with a backslash. For example, pass d'Artagnan as 'd\'Artagnan'. Pass n^m as n\^m. Pass four "score" and seven years as four \"score\" and seven years.

Wildcards are supported. See Wildcards.

Literals are not trimmed. For example, if you send string literal ^ A ^, the server will get a value three characters long that will not match "A".

Features: 

name EQ ^Using cart^

Phases:

logical_name EQ ^phase.test*^

Filtering on a reference value means the ability to filter on field values of the referenced entity.

Reference values have the following syntax:

{<query phrase>[[<logical operator><query phrase>]]}

The Reference field can reference a single entity or many entities, meaning, a multi-reference field. In case of multi-reference fields, the equality operator works as a containment operator.

The defect entity has a reference field to a release entity that is called detected_in_release. We want to filter all defects that were detected in the release named release1:

/defects?query=”detected_in_release EQ {name EQ ^release1^}”

We want to filter all defects that have no reference to any release in the detected_in_release field:

/defects?query=”detected_in_release EQ {null}”

(Note that null is wrapped in curly braces.)

Specifies that the field has no value. Represented as null. This implies that whenever user nullifies a string field from existing value (via PUT), client can send null or empty string ("") and server will store in DB null – this implies that empty string is a non-valid value for a non-nullable field.

"No Value" is relevant for all values except boolean and string values. For specifying "No Value" for strings, see below.

Whenever a value does not exist (for example, in the case where a defect closing date was not defined, since the defect is not closed yet), special keyword null should be defined. This null keyword can be used also in filtering to specify the notion of "no value".

The only manipulation of a string / memo field values from the server side can occur only due to output sanitization functionality.

The REST API doesn’t trims string/memo fields.

Must be wrapped in carets: ^datetime^

Expected date and time format is ISO-8601.

• The date must contain complete date and time information, meaning "date only" is not supported.

• Expected formats are:

  • 2018-06-10T10:13:15Z

  • 2018-03-12T16:42:11%2B01:00 (encoded 2018-03-12T16:42:11+01:00

  • 2018-03-12T16:42:11-01:00

• The date and time format is UTC.

• For create, update and filtering purposes, the API consumer must use the UTC and ISO-8601 formats.

/<some_entities>?query=”<some_date_field_name> LT ^2015-02-25T16:42:11Z^

When filtering, DateTime values behave like strings.

"

\"      ( %5C%22 )

^

\^      ( %5C%5E )

\

\\      ( %5C%5C )

'

\q      ( %5Cq   )

<

\l      ( %5Cl   )

>

\g      ( %5Cg   )

*

N/A

Filtering by this character is not supported

{

\{      ( %5C%7B )

(

\(      ( %5C( )

)

\)      ( %5C) )

[

\[      ( %5Cb )

?

\?      ( %5C%3F )