• Collection Filtering

Collection Filtering

When querying collections, filters can be specified by providing one or more filter[]=…​ parameter.

GET /api/:collection?filter[]=...&filter[]=...&filter[]=...

Syntax for a filter is as follows:

filter[]=attribute op value

By default, filters are logically anded together, for a logical or, prefix the attribute with or as follows:

filter[]=or attribute op value

Where op supports the following operators:

When strings, value to be quoted in single or double quotes. When datetimes, only strict comparison operators are supported.

Example Query of VMs named sample*, created_on > 2019-09-01, and return name and vendor

GET /api/vms?expand=resources&attributes=name,vendor&filter[]=created_on>2019-09-01&filter[]=name='sample%'

Example Query looking for services that are retired but have an unspecified service_id

GET /api/services?expand=resources&attributes=retired&filter[]=service_id=nil&filter[]=retired=true

Example Query of VMs with power_state of on or off:

GET /api/vms?expand=resources&filter[]=power_state=[on,off]

Alternately, you can use the following more verbose syntax using OR:

GET /api/vms?expand=resources&filter[]=power_state=off&filter[]=or%20power_state=on

Example Query of VMs with more than 4 CPU sockets or more than 16,000 MB of RAM (OR):

GET /api/vms?expand=resources&filter[]=num_cpu>4&filter[]=or%20ram_size>16000

Example Query of VMs without a specific value (attribute negation):

GET /api/vms?expand=resources&filter[]=power_state!=unknown

Example Query of VMs where a field is NOT NULL (vms that are either retired or not):

GET /api/vms?expand=resources&filter[]=retired!=nil
GET /api/vms?expand=resources&filter[]=retired!=NULL
GET /api/vms?expand=resources&filter[]=retired!=null

Example Query of VMs using a boolean:

GET /api/vms?expand=resources&filter[]=retired=true

Example Query of VMs created before a specific time:

GET /api/vms?expand=resources&filter[]=created_on<2023-01-01

Attributes specified via the filter[] parameter can include virtual attributes, including one level association of the virtual attribute as follows:

The HTTP OPTIONS request can be used on a collection to display all of the collection specific metadata, including the available virtual attributes. For more information please refer to the Collection Metadata page.

GET /api/vms?attributes=name,vendor,hardware&filter[]=vendor='vmware'&filter[]=hardware.memory_mb>=8192

Here filtering on the virtual attribute hardware including the one level association memory_mb off hardware.