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.

Table 1.6. Available Operators

OperatorTypesValue requiredDescription
eq string | boolean | integer | float | enum | collection (checks for size) | date trueEquality
!eq string | boolean | integer | float | enum | collection (checks for size) | date trueInequality
ne string | boolean | integer | float | enum | collection (checks for size) | date trueInequality
like stringtrueCase sensitive string, match anywhere
!likestringtrueCase sensitive string, not match anywhere
^likestringtrueCase sensitive string, match start
!^likestringtrueCase sensitive string, not match start
$likestringtrueCase sensitive string, match end
!$likestringtrueCase sensitive string, not match end
ilikestringtrueCase insensitive string, match anywhere
!ilikestringtrueCase insensitive string, not match anywhere
^ilikestringtrueCase insensitive string, match start
!^ilikestringtrueCase insensitive string, not match start
$ilikestringtrueCase insensitive string, match end
!$ilikestringtrueCase insensitive string, not match end
gt string | boolean | integer | float | collection (checks for size) | date trueGreater than
ge string | boolean | integer | float | collection (checks for size) | date trueGreater than or equal
lt string | boolean | integer | float | collection (checks for size) | date trueLess than
le string | boolean | integer | float | collection (checks for size) | date trueLess than or equal
null allfalseProperty is null
!nullallfalseProperty is not null
empty collectionfalseCollection is empty
in string | boolean | integer | float | datetrueFind objects matching 1 or more values
!in string | boolean | integer | float | datetrueFind 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