Skip to content

Filtering options

XPKit endpoints that return a list of resources accept query parameters to filter the results.

Filtering options

Equality

To perform an equality filter, provide the field name you want to perform the lookup against and the value you are interested in as follows: ?field_name=value. You should use the dot notation to reference fields within objects.

Example:

?type=Supermarket&name=Local+Convenience+Store&address.state=NSW

Comparison

To perform a comparison filter, provide the field name you want to perform a comparison against and the value you are interested in as follows: ?field_name__operator=value. Where operator is one of the following:

  • in
  • gt (greater than)
  • gte (greater than, or equal to)
  • lt (less than)
  • lte (less than, or equal to)
  • ne (not equal)

For operators that accept more than one value use the pipe character (|) as a separator.

Examples:

  • This will return all resources whose created field is on 2022-01-01

    ?created__gte=2022-01-01T00:00:00Z&created__lte=2022-01-01T23:59:59Z

  • This will return all resources whose product.colours array field contains red and green

    ?product.colours__in=red|green

Note: when providing timestamps make sure values are URL encoded correctly, particularly watch out for the "+" character if a timezone offset is provided:

  • Incorrect: ?created__gte=2022-09-02T04:48:22+10:00
  • Correct: ?created__gte=2022-09-02T04%3A48%3A22%2B10%3A00

Ordering options

Each service will have a default ordering, to override this provide a list of field names alongside the ordering direction: ascending (the default) or descending.

Examples:

  • This will order by the field title in ascending (alphabetical) order

    ?x__order_by=title

  • This will order by the created field in ascending order (oldest first). If any of the resources have the same value for created, these resources will be ordered by the name field in descending order

    ?x__order_by=created__asc|name__desc

Pagination options

When paginating through results the x__limit query parameter can be provided to specify how many results per page are desired.

XPKit supports pagination via page numbers or cursor tokens. When using page numbers any data changes are reflected in real time. This may be a problem in rapidly changing data sets as the same result could appear on multiple pages. To avoid this use tokens, where data is retrieved based on a snapshot in time.

Paginate using page numbers

Provide an x__page query parameter to select the page. Example: ?name=John&x__limit=100&x__page=4.

The value for x__page can be derived from next and previous in responses.

Paginate using tokens

Provide an x__token query parameter to select the page. Example: ?name=John&x__limit=100&x__token=eyJwY....

The value for x__token can be derived from next_token and previous_token in responses.