Collection Filtering

Cratejoy collections can be filtered on properties of the objects in the collection. Unless explicitly excluded, any property can be used to filter the collection. Filters are specified as endpoint arguments (or query parameters) in the same way as limit and page.

📘

Filter syntax

[ relation. ] property [ _**_comparison** ] = value

Brackets ([ ]) indicate optional syntax. Objects, where the value of property passes the comparison to the given value will be returned in the collection.

When a relation is specified, the property refers to the property of a related model. You can only filter on properties of the data model or first level relations.

The following comparisons on properties are supported:

  • eq - (default) equality
  • ne - inequality
  • lt - less than
  • le - less than or equal to
  • gt - greater than
  • ge - greater than or equal to
  • like - wildcard search (use '%' as wildcard character)
  • ilike - wildcard case insensitive search (use '%' as wildcard character)
  • in - appears in list (Comma-separated list)
  • nin - doesn't appear in list (Comma-separated list)
  • is_null - is a null value

Filter Example

/v1/orders/?customer.name__like=%25%20Smith&placed_at__gt=2015-09-01T00:00:00Z
/**
Get orders placed by anyone who's last name is
"Smith" since 9/1/2015
*/
$.get('/v1/orders/',{
  "customer.name__like": "% Smith",  //related property
  "placed_at__gt": "2015-09-01T00:00:00Z"
});

/**
Relations work on one-to-many relationships too.
For instance: get customers with an Austin address
*/
$.get('/v1/customers/', {
  "addresses.city": "Austin"
});
/* 
Find visible products that are between 1.0 and 2.0 pounds,
have a sku that starts with 'SQ700' and who's name starts with 
'T' or later.
*/

$.get('/v1/store/api/products/',{
  ship_weight__gt: 1.0,
  ship_weight__lt: 2.0,
  sku__like: "SQ700%",
  visible: true,
  name__gt: "T"
});