Filter query
Introduction
Filter by (a) specific attribute(s) of your layouts, destinations, folders, etc. The filter_query parameter accepts an attribute and an operation key. Separate the values by a comma to filter by multiple values. The following syntax applies:
layouts?filter_query[attributes.{attribute}][{operation}]=value1,value2
Required fields
If you are querying by a custom attribute, fixed prefix attributes.
is required before the specified attribute field.
If you're not querying by a custom attribute but default entity field, prefix must not be used.
You can query by one of the fields of the following list: title, description, subtype.
attribute: a custom attribute of the list defined by the user
operation: the operation key to apply
One of the list: is, in, not_in, like, not_like, any_in_array, all_in_array, gt_date, lt_date, gt_int, lt_int, gt_float, lt_float
It is possible to use multiple filter queries per request. By default, the applied filters are connected by the AND operator. They must be unique to each other based on attribute - operation key.
It is also possible to apply filters by the OR operator. See OR Conditions for the request syntax.
OR Conditions
OR conditions are supported. Is is possible to apply filters by the [$or] fixed construct, using the following syntax:
?filter_query[$or][attributes.myattribute][operation]=value1&filter_query[$or][attributes.myattribute][operation]=value2&...
Operations
| Operation | Description |
|---|---|
is | Matches a value type. Admitted values:empty_arraynot_empty_arrayemptynot_emptytruefalsenullnot_null |
in | Matches exactly one value |
not_in | Matches all without the given value |
like | Matches exactly one value with a wildcard search. It is possible using * (Example: "john*") |
not_like | Matches all without the given value |
any_in_array | Matches any value of given array |
all_in_array | Must match all values of given array |
gt_date | Greater than date (Format: YYYY-mm-ddTHH:MM:SS+XX:XX) |
lt_date | Less than date (Format: 2024-03-11T10:15:30+01:00) |
gt_int | Greater than integer value |
lt_int | Less than integer value |
gt_float | Greater than float value |
lt_float | Less than float value |
Operation: is
Filter your entries by checking if your custom attribute is of a specific type.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.authors][is]=empty_array | Returns all entries that have no authors |
| filter_query[attributes.authors][is]=not_empty_array | Returns all entries that have assigned authors |
| filter_query[attributes.message][is]=empty | Returns all entries with an empty message |
| ℹ️ All the entries with a blank/empty message field, and also the entries without the message field, are returned. The value empty in the filter is used to identify entries with a blank field and/or entries without a specific field. If you need to select only the entries that have the field message and the value of the message field is blank, you should use the like operator with no value in the filter_query parameter. For example filter_query[message][like]=. | |
| filter_query[attributes.show_in][is]=true | Returns all entries with field show_in that have the value true |
| filter_query[attributes.enabled][is]=false | Returns all entries where enabled is false |
| filter_query[attributes.image][is]=null | Retruns all entries where the image attribute is null |
| filter_query[attributes.featured][is]=not_null | Returns all entries where the featured attribute is not null |
Operation: in
Filter your entries by checking if your custom attribute has a value that is equal to one of the values provided.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.author][in]=authorId | Returns all entries by one author |
| filter_query[attributes.customer][in]=customerId | Returns all entries by one customer |
| filter_query[attributes.title][in]=Title | Returns all entries with field title and the value Title |
| filter_query[attributes.category][in]=post | Returns all entries of one category |
| filter_query[attributes.category][in]=post,news | Returns all entries of category "post" or "news" |
| filter_query[attributes.featured][in]=true | Returns all entries where the field featured is true |
Operation: not_in
Filter your entries by checking if your custom attribute does not have a value that is equal to one of the values provided.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.author][not_in]=authorId | Returns all entries except one author |
| filter_query[attributes.title][not_in]=Title | Returns all entries with field title and not the value Title |
| filter_query[attributes.category][not_in]=post | Returns all entries without one category |
| filter_query[attributes.category][not_in]=post,news | Returns all entries that are not of category "post" or "news" |
| filter_query[attributes.featured][not_in]=true | Returns all entries where the field featured is not true |
Operation: like
Filter your entries by checking if your custom attribute has a value that is "like" the value provided.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.name][like]=john* | Returns all entries starting with the name "John" |
| filter_query[attributes.name][like]=*john | Returns all entries ending with the name "John" |
| filter_query[attributes.name][like]=john | Returns all entries containing the name "John" |
| filter_query[attributes.name][like]=*john* | Returns all entries containing the name "John" |
| filter_query[attributes.name][like]= | Returns all entries with the field name with empty value. The entries without the name field will not be included |
Operation: not_like
Filter your entries by checking if your custom attribute has a value that is "not_like" the value provided.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.name][not_like]=john* | Returns all entries not starting with the name "John" |
| filter_query[attributes.name][not_like]=*john* | Returns all entries not containing the name "John" |
Operation: any_in_array
Filter your entries by checking if your custom array attribute contains one of the values provided. As soon as one of the provided values separated with , are in the array field, the entry object will be in the response.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.categories][any_in_array]=post,news | Returns all entries of category post or news in field categories |
| filter_query[attributes.tags][any_in_array]=food,health | Returns all entries of category food or health |
| filter_query[attributes.related_products][any_in_array]=product-one-id,product-two-id | Returns all entries with product-one or product-two in the field related_products |
Operation: all_in_array
Filter your entries by checking if your custom array attribute contains all of the values provided. As soon as all of the provided values separated with , are in the array field, the entry object will be in the response.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.categories][all_in_array]=post,news | Returns all entries of category post and news in field categories |
| filter_query[attributes.tags][all_in_array]=food,health | Returns all entries of category food and health |
| filter_query[attributes.related_products][all_in_array]=product-one-id,product-two-id | Returns all entries with product-one and product-two in the field related_products |
Operation: gt_date
Think of it AFTER a specific date. Allows you to filter fields of type date/datetime (Format: YYYY-mm-ddTHH:MM:SS+HH:MM). Returns all entries that are greater (eg. later) than the provided value.
You can create custom dates that allow you to schedule posts, launch products and with this query see all entries that are scheduled after a specific date, schedule christmas teaser. Creating a field with the type date allows your frontend / server side implementation to query those specific entries.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.schedule][gt_date]=2019-12-24T10:30:00+01:00 | Returns all entries with date field schedule after "2019-12-24 10:30” |
Operation: lt_date
Think of it BEFORE a specific date. Allows you to filter fields of type date/datetime (Format: YYYY-mm-ddTHH:MM:SS+HH:MM). Returns all entries that are lower than (eg. before) the provided date.
You can create custom dates that allow you to schedule posts, launch products, schedule christmas teaser and more. Creating a field with the type date allows your frontend / server side implementation to query all entries before a specific date (eg. today)
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.schedule][lt_date]=2019-12-24T10:30:00+01:00 | Returns all entries with date field schedule before "2019-12-24 10:30" |
Operation: gt_int
Allows you to filter fields of type number, string (number value), or custom field type with numbers in the schema. Returns all entries that are greater than the provided value.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.price][gt_int]=100 | Returns all entries with price field greater than 100 |
| filter_query[attributes.price][gt_int]=1999 | Returns all entries with price field greater than 1999 (no thousand separator) |
Operation: lt_int
Allows you to filter fields of type number, or custom field type with numbers in the schema. Returns all entries that are lower than the provided value.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.price][lt_int]=100 | Returns all entries with price field lower than 100 |
| filter_query[attributes.price][lt_int]=1999 | Returns all entries with price field lower than 1999 (no thousand separator) |
Operation: gt_float
Allows you to filter fields of type float, string (float value), or custom field type with numbers in the schema. Returns all entries that are greater than the provided value.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.price][gt_float]=100.50 | Returns all entries with price field greater than 100.50 |
| filter_query[attributes.price][gt_float]=99.50 | Returns all entries with price field greater than 99.50 |
| filter_query[attributes.price][gt_float]=1999.50 | Returns all entries with price field greater than 1999.50 (no thousand separator) |
Operation: lt_float
Allows you to filter fields of type number, or custom field type with numbers in the schema. Returns all entries that are lower than the provided value.
Example use cases
| Filter query | Description |
|---|---|
| filter_query[attributes.price][lt_float]=100.50 | Returns all entries with price field lower than 100.50 |
| filter_query[attributes.price][lt_float]=99.50 | Returns all entries with price field lower than 99.50 |
| filter_query[attributes.price][lt_float]=1999.50 | Returns all entries with price field lower than 1999.50 (no thousand separator) |