Share this page

# Query

This section provides information about querying by filtering values of fields. Only the entities that match the query are returned by the REST API during a GET operation on collections.

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

In this topic:

## 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/<space_id>/workspaces/<workspace_id>/{entity}?query="query statement"`

- The query statement is contained within double quotes: "query statement"

- The query statement has the following syntax:

  " `<query phrase>[[<logical operator><query phrase>]]` "

  This means that when a query statement contains more than one query phrase, separate each query phrase with an And (;) or an Or (||) logical operator.

  Note: When filtering field metadata, certain limitations exist. For example, the Or (||) logical operator is not supported. For details, see Filter field metadata using the URI.

## Query phrase

- The query phrase of a query statement has the following syntax:

  `( [negate keyword] ( "<field name> <comparison operator> <value>" ) )`

  Note: Pay attention to the opening and closing parentheses in the syntax for the query phrase.

- The query phrase can be enclosed in parenthesis.

## Operators

This section lists the supported operators and the various types of operators that are available.

### Supported operators by data type

The following are the supported operators by data type. The values provided in the query should be consistent with the data types declared by the fields.

Data Type | EQ | LT | GT | LE | GE | IN | BTW
--- | --- | --- | --- | --- | --- | --- | ---
Integer |  |  |  |  |  |  |
Boolean |  |  |  |  |  |  |
DateTime |  |  |  |  |  |  |
String |  |  |  |  |  |  |
Memo |  |  |  |  |  |  |
Reference |  |  |  |  |  |  |

### Operator terms

This section lists the various types of operators that are available: Comparison and Logical.

Comparison operators

Comparison operators are used to separate between field names and their values.

Operator | Functionality | Example
--- | --- | ---
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 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 ( )

Logical operators

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

Operator | Functionality
--- | ---
; | And
|| | Or
! | Not The negation operator ! is optional. This operator reverses the meaning of the subsequent operand.

### 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)
--- | ---
() | 1
! | 2
; | 3
|| | 4

Example: The following statements are equivalent:

- `"(!name EQ ^test^);flag EQ true"`

- `"!name EQ ^test^;flag EQ true"`

## Value terms

This table describes the value terms, their format, and their implementation.

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 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*^`
String-based | When filtering, DateTime values behave like strings. See DateTime. | None
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. Note: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. | None
DateTime | 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. | None

## Special characters

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 that character, use the escape character. This table shows some common examples:

Character | Escaped Character (URI Encoded)
--- | ---
" | \" ( %5C%22 )
^ | \^ ( %5C%5E )
\ | \\ ( %5C%5C )
' | \q ( %5Cq )
< | \l ( %5Cl )
> | \g ( %5Cg )
* | Note: Filtering by this character is not supported
{ | \{ ( %5C%7B )
( | \( ( %5C( )
) | \) ( %5C) )
[ | \[ ( %5Cb )
? | \? ( %5C%3F )

## Wildcards

The supported wildcard 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.

- `/<some_entities>?query="<some_string_field_name> EQ ^existence^"`

- `/<some_entities>?query="<some_string_field_name> EQ ^test*^"`

## Query across multiple workspaces

You can query data from multiple workspaces within a shared space. You can also specify that the query include only workspaces with certain attributes – for example, only active workspaces.

To query data from multiple workspaces in a shared space, use the cross_workspace parameter. You can use it to include only specific workspaces, or include all workspaces assigned to the user by using the * wildcard character.

Example: The first query retrieves defects from all workspaces assigned to the user within the shared space. The second query retrieves defects from two specific workspaces.

- `GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?fields=id&cross_workspace=*`
- `GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?fields=id&cross_workspace=1001,1002`

To include data only from workspaces with specific attributes, use the cross_workspace parameter and add the cross_workspace_query parameter.

Example: The following query retrieves defects from all active workspaces assigned to the user within the shared space.

`GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?fields=id&cross_workspace=*&cross_workspace_query=(active=1)`

## Examples

The following examples show how to work with queries and filters.

### Filtering with IN and BTW

- Filter all defects which were detected by a specific user:

  `GET .../defects?query="detected_by EQ {[current_user]}"`

  `GET .../defects?query="detected_by={ id IN 1001,1002,1003}"`

  `GET .../defects?query="detected_by={ id BTW 1001...1003}"`

  `GET .../defects?query="detected_by={ id IN [current_user],1001}"`

- Filter all defects which were detected by the logged in user and is part of specific team:

  `GET .../defects/query="detected_by EQ {[current_user];teams EQ {id EQ 2005}}"`

- Filter all defects where the release is in a list of releases:

  `GET .../defects?query="release EQ {[current_release]}"`

  `GET .../defects?query="release={id IN [current_release], 1002}"`

  `GET .../defects?query="release={id IN 1001, 1002}"`

### Filtering on user tags

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”

            }

        ]

    }

The following filter queries retrieve all of the above defects:

- `GET .../defects?query="user_tags EQ {id EQ 1001}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001||id EQ 2005}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001}||user_tags EQ {id EQ 2005}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001||id EQ 500000}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001}||user_tags EQ {id EQ 500000}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001;id EQ 3008}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001};user_tags EQ {id EQ 3008}"`

- `GET .../defects?query="user_tags EQ {(id EQ 1001;id EQ 2005;id EQ 3008)||id EQ 50000000}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001;id EQ 2005;id EQ 3008}||user_tags EQ {id EQ 50000000}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001||(id EQ 2005;id EQ 50000000)}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001}||(user_tags EQ {id EQ 2005}; user_tags EQ {id EQ 50000000})"`

- `GET .../defects?query="user_tags EQ {id EQ 1001}||user_tags EQ {null}"`

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

- `GET .../defects?query="user_tags EQ {id EQ 1001;id EQ 50000000}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001};user_tags EQ {id EQ 50000000}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001;(id EQ 5000000||id EQ 7000000)}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001};user_tags EQ {id EQ 5000000||id EQ 7000000}"`

- `GET .../defects?query="user_tags EQ {id EQ 1001};(user_tags EQ {id EQ 5000000}|| user_tags EQ {id EQ 7000000})"`

- `GET .../defects?query="user_tags EQ {id EQ 1001};user_tags EQ {null}"`

## See also

- Query a collection
- Cross-filter

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: