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?
Except where otherwise noted, content on this site is licensed under the Development License Agreement.