Filtering a Collection of Entities

A GET statement that returns a large amount of data can stress the database server and cause performance degradation for all users. To minimize the impact, you can filter the entities to be returned and retrieve only the fields you need.

Guidelines

The following table lists the guidelines for adding a query:

Encode URL

Queries sent by applications must be URL encoded.

For example, to submit query {status[NOT (Ready or Design)]}, send %7Bstatus%5BNOT%20(Ready%20or%20Design)%5D%7D. See also URL encoding.

The examples in this topic are not URL encoded so that they are easier to read.

Contain query in curly bracketsThe filter of a query URL is contained in curly brackets "{}".
Contain field expression in square bracketsThe expression applied to a field is contained in square brackets "[]".
Separate fields by semicolonThe field delimiter is a semicolon ";" .
Supported operation between fields

The only operation supported between fields is AND. The AND operation is implicit and is not specified in the query syntax. Only the ";" delimiter is specified.

Can use space in a query

You can generally use spaces in an query entered in a browser.

Split long queries

If your query is long, we recommend you split it into multiple requests.

Alternatively, you can increase the requestHeaderSize in the Jetty configuration. However, this may result in performance issues.

To configure the request header size:

  1. Open the jetty.xml file located in the {ALM deploy folder}/server/conf/ directory.

  2. Change the value of the <Set name="requestHeaderSize"> attribute.

Query statement

To filter the entities to be returned, you can add a query to the URL, which is comprised of at least one query condition.

A query statement can be applied to any GET on a collection of entities.

Example: GET .../qcbin/rest/domains/{domain}/projects/{project}/tests?query={query statement}.

The query statement is contained within curly brackets {}. It has the following syntax:

<field name>[query condition]; <field name>[query condition]; <field name>[query condition]

  • A query statement can contain more than one query phrase, separated by semicolons (;).

  • To identify a field, use its logical name. See Field Names

  • To define query conditions, see Query condition.

Query condition

A query condition is contained within square brackets [].

Example: tests?query={id[GT 1 AND NOT 5]; status[Ready or Design]}

This query specifies any test whose ID is bigger than one, excluding test 5, and whose status is Ready or Design.

A query condition can include the following elements:

Comparison operators

Comparison operators separate between field names and their values. The following comparison operators are supported:

Comparison OperatorDetailsExample

GT

>

Represents "greater than".

  • Starting from 24.1 P1, you can use either GT or >. However, OpenText recommends you use GT in case your organization has strict security policies.

  • Before 24.1 P1, you can only use >.

id GT 1001

LT

<

Represents "less than".

  • Starting from 24.1 P1, you can use either LT or <. However, OpenText recommends you use LT in case your organization has strict security policies.

  • Before 24.1 P1, you can only use <.

id LT 1001

EQ

=

Represents "equal to".

  • Starting from 24.1 P1, you can use either EQ or =. However, OpenText recommends you use EQ in case your organization has strict security policies.

  • Before 24.1 P1, you can only use =.

id EQ 1001

GE

>=

Represents "greater than or equal to".

  • Starting from 24.1 P1, you can use either GE or >=. However, OpenText recommends you use GE in case your organization has strict security policies.

  • Before 24.1 P1, you can only use >=.

id GE 1001

LE

<=

Represents "less than or equal to".

  • Starting from 24.1 P1, you can use either LE or <=. However, OpenText recommends you use LE in case your organization has strict security policies.

  • Before 24.1 P1, you can only use <=.

id LE 1001

Logical operators

Logical operators are used to separate between conditions to form a logical statement. The following logical operators are supported:

Logical OperatorDetails
ANDThe AND operator returns true if both conditions are true.
ORThe OR operator returns true if at least one of the conditions is true.
NOTThe NOT operator negates the result of a condition, returning true if the condition is false and false if the condition is true.

Literals

Literals are strings that represent the value of an expression. If a value contains spaces, it must be contained within single or double quotes. Literals can contain the '*' wild card.

Parentheses

Parentheses are used after a logical operator to control the order of operations and specify the grouping of conditions.

Examples of valid queries

    GT 1 AND ( LT 3 OR GT 5 )
    GT 1 AND (LT "3" OR GT 5)
    GT 1 AND = "( LT 3 OR GT 5)"
    1 AND (LT 3 OR GT 5 )
    GT 1 AND NOT (LT 3 OR GT 5)
    GT 1 OR NOT (LT 3 OR GT 5)
    GE 1 or not (LT 3 OR GT 5)
    AAAAAP*
    aaa or not cccccc
    aaa or cccccc
    aaa or GT cccccc
    aaa or not GT cccccc
    aaa or not GT 'cccccc' AND fff
    not ( Design Or Repair )
    = 1 AND (LT 3 OR GT 5 )
    =aaa or cccccc
    =AAAAAP*

Cross filters

If there is a relational connection between two entity types, a collection can be filtered on the related entities. Use the unique alias that represents the relation for the cross filter. For an example of how to know if an alias is unique, see the example in the Relations topic.

The expression for the related entity is <alias>.<logical field name><filter expression>.

Example: Because tests can be linked to defects, the tests collection can be filtered by defect fields:

.../tests?query={connected-to-defect.name["Widget wobbles*"]}

See Relations, the relations resource and the Relation schema (Schema Reference).

Exclusive filter

To return the resources that do not meet the conditions applied to an entity, add {entity}.inclusive-filter[false] to the filter.

The effect is to exclude the resources that would be returned if inclusive-filter[false] were not specified and to return the rest.

Example: /tests?query={defect.id[1];defect.status[Closed or Fixed];requirement.id[1];defect.inclusive-filter[false]}

This query returns tests that are linked to the requirement whose ID is 1, excluding tests linked to the defect whose ID is 1 and excluding tests linked to defects that are fixed or closed.

Note that since inclusive-filter[false] is applied to the defect entity, only the clauses for defect are treated as exclusion clauses. The requirement clause is applied as an inclusion clause.

Retrieve only the fields you need

To retrieve only the fields you need, you can add a fields clause to the URL.

Examples

Single entity expressions

tests?query={status[NOT (Ready or Design)]}
tests?query={status[NOT (Ready or Design)]}
tests?query={status[Ready or NOT Design]}
tests?query={id[GE 1 And NOT = 5]}
tests?query={exec-status['Not Completed']}
tests?query={exec-status['Not Com*']}

Cross filter expressions with entity names

Tests in status "Ready" that are linked to defects assigned to user SallyQA:
tests?query={status[Ready]; defect.owner[SallyQA]}

Tests that are linked to defects assigned to user joe:
tests?query={defect.owner[joe]}

Cross filter expressions with relation aliases

Design steps that call tests named D*:
design-steps?query={used-by-test.name[D*]}

Design steps that are part of tests named S*:
design-steps?query={has-parts-test.name[S*]}