Skip to content

IoT File Service – Filtering

Search Filter Operators

The allowed operators in a filter clause are:

  • eq or =
  • gte or >=
  • gt or >
  • lte or <=
  • lt or <

Filters can use the wildcard character * and be combined using the and operator (or is not supported). Blanks in the wrong place and invalid parameters will lead to the filter being ignored. Filtering is possible on the following fields:

  • File update timestamp
  • File path
  • File name

Note

Timestamps are stored as strings in ISO 8601 format in the UTC timezone. This means that in order to find an entity with the timestamp "2017-09-21T14:08:22.345+02:00" you have to search for "2017-09-21T12:08:22.345Z".

The result set of a filter request can be sorted with the order parameter. When sorting by name, the result is automatically sorted by path as well. Sorting is only allowed on exactly one property per request and sorting can only be done on the following properties:

  • File update timestamp
  • File path
  • File name

By default, GET requests for a list of files return only the first up to 500 files. Use the offset parameter in the query string of the GET request to adjust at which file to start the list. Use the limit parameter to adjust how many files to return. Be aware that the offset parameter is limited to 10,000. It is recommended to refine the search to limit the response to small result sets.

Search Filter Syntax

The following table lists examples for the search filter syntax for each operator:

Operator Description Example (unencoded)
eq equal to specified value path eq 'my/path*'
lt less than specified value updated lt '2018-07-27T17:05:31.208Z'
gt greater than specified value updated gt '2018-07-27T17:05:31.208Z'
lte less than or equal to specified value updated lte '2018-07-27T17:05:31.208Z'
gte greater than or equal to specified value updated gte '2018-07-27T17:05:31.208Z'
and combine two conditions name eq 'result*.txt' and updated lte '2018-07-23T13:16:07.078Z'

The following table lists examples for the sort syntax:

Field Description Example (unencoded)
name sort by file name order=name asc/desc
path sort by file path order=path
updated sort by updated timestamp order=updated

Example

In this example, there is an entity instance with an ID of 978528e7a124458f87c8f1d38fd9400f. The goal is to search for test result files sorted by file name in alphabetically ascending order with a limit of 10 results and an offset of 1 (i.e., starting at the second file). Make a GET request to:

https://{host}/api/iotfile/v3/files/978528e7a124458f87c8f1d38fd9400f?filter=name eq 'result*.txt' &order=name&limit=10&offset=1

Here, the response is:

[
    {
        "name": "result072108.txt",
        "path": "",
        "type": "abc",
        "description": null,
        "size": 4,
        "timestamp": null,
        "created": "2018-09-04T01:55:32.351Z",
        "updated": "2018-09-04T01:55:32.351Z",
        "createdBy": "f4d5493f-8a1b-421e-9b9c-bb6a963a0837",
        "updatedBy": "f4d5493f-8a1b-421e-9b9c-bb6a963a0837",
        "tenantId": "8b9ff6977f58459b979a5ae7cf6828bd",
        "storagePrefix": null,
        "etag": 0
    },
    {
        "name": "result082108.txt",
        "path": "",
        "type": "abc",
        "description": null,
        "size": 4,
        "timestamp": null,
        "created": "2018-09-04T01:55:38.299Z",
        "updated": "2018-09-04T01:55:38.299Z",
        "createdBy": "f4d5493f-8a1b-421e-9b9c-bb6a963a0837",
        "updatedBy": "f4d5493f-8a1b-421e-9b9c-bb6a963a0837",
        "tenantId": "8b9ff6977f58459b979a5ae7cf6828bd",
        "storagePrefix": null,
        "etag": 0
    }
]

In this example only two items fulfilled the search parameters. Otherwise up to 10 entries would have returned.

Any questions left?

Ask the community

Except where otherwise noted, content on this site is licensed under the Development License Agreement.

Last update: July 13, 2021