Query

You can query entities by filtering values of fields.

Filtering applies to the GET operation on collections.

For details on cross-filtering, see Cross-filter.

Query statement

To filter, use a query statement, which is comprised of at least one query phrase.

The query statement is appended to the end of GET method.

Example: GET .../api/shared_spaces/{shared_space_uid}/workspaces/{workspace_id}/{entity}?query="query statement"

Query phrase

Operators

Supported operators, by data type

The values provided in the query should be consistent with the data types declared by the fields.

Data Type

=

<

>

<=

>=

Integer

Boolean

Date / DateTime

String

Memo

Reference

Back to top

Using operators

Operator type

Operator

Functionality

Example

Basic operators Comparison operators separate between field names and their values:

EQ

Equals to

id EQ 1001

LT

Less than

id LT 1001

GT

Greater than

id GT 1001

LE

Less than or equals to

id LE 1001

GE

Greater than or equals to

id GE 1001

Logical operators Logical operators are used to separate between query phrases or query statements.
 

;

And

 
 

||

Or

 
  !

Not

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

 

Understanding operator precedence

The parenthesis has the highest precedence among all other operators, and controls the order in which the conditions are evaluated.

Parenthetical expressions can be nested.

Operator

Rank (low number = higher rank)

Example

()

1

The following statements are equivalent: 

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

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

Note: tests are a technical preview. Until made public, send an HPECLIENTTYPE header with the value: HPE_REST_API_TECH_PREVIEW in your requests.

!

2

; 3
|| 4

Values

Type Description Examples

Numeric

Numeric values are placed after the comparison operator.

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

id GT 1

Boolean

Valid values: true or false.

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

has_attachments EQ true
String / Memo

Must be wrapped in carets: ^string^

Escaping of special characters in strings is supported. See Escaping 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 Using 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*^

String-based When filtering, Date and DateTime values behave like strings. See Date / DateTime.  
Reference

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.)

"No Value"

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.

An empty string is not a valid value for a non-nullable field. For a nullable string field, null does not match an empty string.
 
Date / DateTime

Must be wrapped in carets: ^date^

Expected date and time format is ISO-8601.

Example

  • 2015-02-25T16:42:11Z

  • 2015-02-25T16:42:11+02:00

The date and time is UTC.

For filtering purposes, should be in UTC and ISO-8601 format.

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

When filtering, Date and DateTime values behave like strings.

 

Back to top

Escaping special characters

The escaping of special character in string values is supported (if the string you are searching for contains one of the following characters, and you would like to filter by the character):

Character

Escaped Character (URI Encoded)

Comments

"

\"      ( %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 )

 

Back to top

Using wildcards

The wildcard supported is the * asterisk. Any character matches the asterisk.

To filter for a string that ... Specify wildcard... Matches...
Ends with ending *ending the_ending ; theending; ending
Starts with starting starting* starting_here ; startinghere, starting

Example: The first example shows a direct match of the string existence. The second example returns any value that starts with test.

Back to top

Examples

A defect is tagged with multiple user tags:

{
    “type”: “defect”,
    “user_tags”: [
        {
            “id”: 1001,
            “type”: “user_tag”
        },
        {
            “id”: 2005,
            “type”: “user_tag”
        },
        {
            “id”: 3008,
            “type”: “user_tag”
        }
    ]
}

Back to top

The following filter queries retrieve all of the above defects: 

Back to top

The following filter queries do not retrieve all the above defects: 

Back to top

See also: