1.7 Metadata object filter

To filter the metadata there are several filter operations that can be applied to the returned list of metadata. The format of the filter itself is straight-forward and follows the pattern property:operator:value , where property is the property on the metadata you want to filter on, operator is the comparison operator you want to perform and value is the value to check against (not all operators require value). Please see the schema section to discover which properties are available. Recursive filtering, ie. filtering on associated objects or collection of objects, are supported as well.

Available Operators
Operator Types Value required Description
eq string | boolean | integer | float | enum | collection (checks for size) | date true Equality
!eq string | boolean | integer | float | enum | collection (checks for size) | date true Inequality
ne string | boolean | integer | float | enum | collection (checks for size) | date true Inequality
like string true Case sensitive string, match anywhere
!like string true Case sensitive string, not match anywhere
$like string true Case sensitive string, match start
!$like string true Case sensitive string, not match start
like$ string true Case sensitive string, match end
!like$ string true Case sensitive string, not match end
ilike string true Case insensitive string, match anywhere
!ilike string true Case insensitive string, not match anywhere
$ilike string true Case insensitive string, match start
!$ilike string true Case insensitive string, not match start
ilike$ string true Case insensitive string, match end
!ilike$ string true Case insensitive string, not match end
gt string | boolean | integer | float | collection (checks for size) | date true Greater than
ge string | boolean | integer | float | collection (checks for size) | date true Greater than or equal
lt string | boolean | integer | float | collection (checks for size) | date true Less than
le string | boolean | integer | float | collection (checks for size) | date true Less than or equal
null all false Property is null
!null all false Property is not null
empty collection false Collection is empty
token string true Match on multiple tokens in search property
!token string true Not match on multiple tokens in search property
in string | boolean | integer | float | date true Find objects matching 1 or more values
!in string | boolean | integer | float | date true Find objects not matching 1 or more values

Operators will be applied as logical and query, if you need a or query, you can have a look at our in filter (also have a look at the section below). The filtering mechanism allows for recursion. See below for some examples.

Get data elements with id property ID1 or ID2:

/api/26/dataElements?filter=id:eq:ID1&filter=id:eq:ID2

Get all data elements which has the dataSet with id ID1:

/api/26/dataElements?filter=dataSetElements.dataSet.id:eq:ID1

Get all data elements with aggregation operator “sum” and value type “int”:

/api/26/dataElements.json?filter=aggregationOperator:eq:sum&filter=type:eq:int

You can do filtering within collections, e.g. to get data elements which are members of the “ANC” data element group you can use the following query using the id property of the associated data element groups:

/api/26/dataElements.json?filter=dataElementGroups.id:eq:qfxEYY9xAl6

Since all operators are and by default, you can’t find a data element matching more than one id, for that purpose you can use the in operator.

/api/26/dataElements.json?filter=id:in:[fbfJHSPpUQD,cYeuwXTCPkU]

1.7.1 Logical operators

As mentioned in the section before, the default logical operator applied to the filters are AND which means that all object filters must be matched. There are however cases where you want to match on one of several filters (maybe id and code field) and in those cases it is possible to switch the root logical operator from AND to OR using the rootJunction parameter.

Example: Normal filtering where both id and code must match to have a result returned

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1

Example: Filtering where the logical operator has been switched to OR and now only one of the filters must match to have a result returned

/api/dataElements.json?filter=id:in:[id1,id2]&filter=code:eq:code1&rootJunction=OR