Skip to main content

Filtering (client side)

Supported operators​

The response returned from the platform can also be filtered on the client side by using the filter argument.

The filter parameter uses a query language which supports the following operators:

operatordescriptionusage
likewildcard match (case insensitive)--filter "c8y_Hardware.serialNumber like *223*"
notlikeinverted wildcard match (case insensitive)--filter "c8y_Hardware.serialNumber notlike *223*"
matchregex match (case insensitive)--filter "c8y_Hardware.serialNumber match *223*"
matchinverted regex match (case insensitive)--filter "c8y_Hardware.serialNumber notmatch *223*"
eqequals--filter "count eq 3"
neqnot equals--filter "count neq 3"
gtgreater than (numbers only)--filter "count gt 3"
gtegreater than or equal to (numbers only)--filter "count ge 3"
ltless than (numbers only)--filter "count lt 3"
lteless than or equal to (numbers only)--filter "count le 3"
leneqequality match length of (string/array/map)--filter "name leneq 10" or --filter "childAdditions.references leneq 1"
lenneqinverted equality match length of (string/array/map)--filter "name lenneq 10" or --filter "childAdditions.references lenneq 1"
lengtmatch length greater than value of (string/array/map)--filter "name lengt 10" or --filter "childAdditions.references lengt 1"
lengtematch length greater than or equal to value of (string/array/map)--filter "name lengte 10" or --filter "childAdditions.references lengte 1"
lenltmatch length less than value of (string/array/map)--filter "name lenlt 10" or --filter "childAdditions.references lenlt 1"
lenltematch length less than or equal to value of (string/array/map)--filter "name lenlte 10" or --filter "childAdditions.references lenlte 1"
dateltmatch date less than (older) to value of (datetime/relative)--filter "creationTime datelt 2022-01-02T12:00"
datelte (or 'olderthan')match date less than (older) or equal to value of (datetime/relative)--filter "creationTime datelte 2022-01-02T12:00"
dategtmatch date greater than (newer) to value of (datetime/relative)--filter "creationTime dategt 2022-01-02T12:00"
dategte (or 'newerthan')match date greater than (newer) or equal to value of (datetime/relative)--filter "creationTime dategte 2022-01-02T12:00"
versionmatch a version or version range--filter "c8y_Firmware.version version >1.0.1, <=2.0.0"
hasmatch when an object has a given key/property--filter "has name
nothasmatch when an object does not have a given key/property--filter "nothas name

Examples​

caution

It is highly recommended to use server side filtering where you can (e.g. inventory query api). Server side filtering is much more efficient and it reduces the amount of data that the server needs to transfer to the client.

But if you have a very specific use-case which can't be solved via server API then this section is for you. Remember you an also use jq and grep if can't find the right client side filtering operator.

Filtering application with name that start with "co*"​

c8y applications list --pageSize 100 --filter "name like co*"
output
| id         | name         | key                          | type        | availability |
|------------|--------------|------------------------------|-------------|--------------|
| 8          | cockpit      | cockpit-application-key      | HOSTED      | MARKET       |

Filtering list of inventory (client side) by lastUpdated date between a given range​

A date string can be used and it will be converted to your local timezone. i.e. "2022-01-18" -> "2022-01-18T00:00:00Z" when running on a machine using UTC time.

c8y inventory list \
    --pageSize 20 \
    --filter "lastUpdated newerthan 2022-01-18" \
    --filter "lastUpdated olderthan 2022-01-18 15:00" \
    --select id,lastUpdated
output
| id         | lastUpdated                   |
|------------|-------------------------------|
| 4207       | 2022-01-18T08:20:59.301Z      |
| 4209       | 2022-01-18T08:21:00.204Z      |
| 3211       | 2022-01-18T08:21:01.394Z      |
| 2702       | 2022-01-18T09:29:23.990Z      |
| 4115       | 2022-01-18T09:29:26.280Z      |
| 4116       | 2022-01-18T09:29:28.761Z      |
| 4150       | 2022-01-18T09:45:14.382Z      |
| 2721       | 2022-01-18T09:45:16.703Z      |
| 4153       | 2022-01-18T09:45:19.232Z      |
| 4190       | 2022-01-18T11:26:46.037Z      |
| 4751       | 2022-01-18T11:26:48.982Z      |
| 2739       | 2022-01-18T11:26:52.188Z      |
| 4767       | 2022-01-18T14:55:24.515Z      |
| 2758       | 2022-01-18T14:55:26.860Z      |
| 2759       | 2022-01-18T14:55:29.349Z      |

Filtering list of inventory (client side) by creationTime date using a relative timestamp​

Filter a list of inventory items and filter the managed objects which were created in the last 2 hours.

c8y inventory list \
    --pageSize 2000 \
    --filter "creationTime newerthan -2h" \
    --select id,creationTime
output
| id         | creationTime                  |
|------------|-------------------------------|
| 53758      | 2022-02-16T18:37:26.682Z      |
| 53791      | 2022-02-16T18:49:35.689Z      |
| 55624      | 2022-02-16T18:59:43.222Z      |

Filtering by a version​

The version filter allows easy version filtering which is not normally possible with string comparisons.

c8y devices list --pageSize 100 --filter "c8y_Firmware.version version >=1.10.0" -o json -c
output
{"id": "11111", "c8y_Firmware": {"version": "1.10.0+deb10"}}
{"id": "22222", "c8y_Firmware": {"version": "1.11.1"}}

Alternatively you can apply version constraints (min and max versions) by using a comma separator.

c8y devices list --pageSize 100 --filter "c8y_Firmware.version version >=1.10.0, <1.11.0" -o json -c
output
{"id": "11111", "c8y_Firmware": {"version": "1.10.0+deb10"}}
note

If the version is an empty string or invalid version, it is treated as "0.0.0". This can be filtered out using ">0.0.0"