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.

Filter entities to be returned

To filter the entities to be returned, you can add a query to the URL. For example: /tests?query={query statement}. A query can be applied to any GET on a collection of entities.

Query syntax

The elements of a query include the following:

Comparison operators<, >, <>, >=, <=
Logical operatorsand, or, not
Literals
  • String 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.
    • Pairs of parenthesis()
    Field nameUse logical names to identify the fields. See Field Names

    Example: tests?query={id[>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.

        > 1 AND ( < 3 OR > 5 )
    > 1 AND (< "3" OR > 5)
    > 1 AND = "( < 3 OR > 5)"
    1 AND (<3 OR >5 )
    > "aaa" or not ( <> "bbbb" OR >= "cccccc")
    >1 AND NOT (<3 OR >5)
    >1 OR NOT (<3 OR >5)
    >=1 or not (<3 OR >5)
    AAAAAP*
    > aaa or not ( <> bbbb OR >= cccccc)
    aaa or not cccccc
    aaa or cccccc
    aaa or > cccccc
    aaa or not > cccccc
    aaa or not > 'cccccc' AND fff
    not ( Design Or Repair )
    = 1 AND (<3 OR >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 XSD.

    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[>=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*]}