Filtering

Filtering is not supported on all APIs, however it is supported extensively on the reporting APIs and starting in version 1.42 the filter_expression parameter will be available on APIs that return lists of objects.

The use of filters is highly recommended to reduce the size of the data being retrieved and to reduce the impact on other users in the system.

Filtering with Datetime Fields

Datetime field filters can be a little tricky and may not always behave as intended.

The format for datetime fields follows the ISO format:
YYYY-MM-DDThh:mm:ss(TZ) where YYYY is year, MM is month, DD is day, hh is hour in 24 hourformat, mm is minute and ss in seconds.

Most Datetime fields in Vitruvi are timezone aware. If no timezone is specified, the comparison will be done using the server set timezone or Zulu time which can lead to unpredictable results.

It is recommended that timezones be explicitly specified to ensure consistent results.

If the timezone is not important to the query result, it is recommended that Zulu (UTC) time is still specified by appending Z to the datetime so that returned results are consistent between calls. For example, 2022-05-06T20:15:00Z.

Timezones can also be specified with offsets by using the format +/-hh:mm. For example, 2022-05-06T20:15:00-5:00 is the equivalent of 2022-05-07T01:13:11Z.

If a filter criteria is specified with only a date, the filter will first convert the criteria to a datetime (using the timezone of the server), then do its comparisons. It DOES NOT convert the field's value to a date for a comparison EXCEPT for the raw APIs when using the __date operator described below.

For example a filter criteria like modified='2022-01-01' will be treated as modified='2022-01-01T00:00:00Z'. Should a value in the data set contain the field modified='2022-01-01T13:33:21Z', the filter will NOT return the record due to the time part of the value not being equal.

Filtering _Query APIs

For details on using filters for the query API endpoints, see Filtering _Query APIs.

Filtering on all other List APIs

For details on using filters on any other APIs that return a list of objects, see Filtering List APIs.

Filtering Raw APIs

🚧

Deprecated

Starting in version 1.42, this method of filtering results from the raw API endpoint will be deprecated in favor of the new filter_expression parameter. See Filtering List APIs above.

For details on using filters for the raw API endpoint, see Filtering Raw APIs.