Filtering

The Objective search API supports all common filtering operations. To see filters in action, checkout this demo!

Check out the code for the demo to see real-world examples of filtering code: https://github.com/objective-inc/examples/tree/main/apps/ecommerce-quickstart/components/filter

Applying filters

Filters are applied by using the filter_query= query parameter. This parameter takes a string value that represents the filter query to be applied to the results.

Filters may be applied on fields in the object. In order to efficiently filter on a field, list that field name in the list of filterable fields when creating the index.

URL Encoding

Filter queries should be URL encoded before being sent to the API. This means that filter_query=color:"dark green" should be sent to the API as filter_query%3Dcolor%3A%22dark%20green%22. For more info on URL encoding, see https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding.

Field types

In order to filter on a field, the Index must be configured with this field as filterable, and the field must have a type. See the create Index documentation for how to index a field as filterable. The following types are supported for filtering:

• string
• int
• float
• bool
• datetime (we support RFC 3339 formatted dates. For example 2015-11-03T15:01:00.05Z)
• geo coordinate

Fields that are indexed as filterable must have homogenous types. This means that all of the values of the field that are indexed must share the same type. If a value in an Object does not conform to the type defined in the index configuration that Object will fail to index, and thus will not be filterable. This means this Object will not appear in results when filtered upon.

Field names

Field names must contain only alphanumeric characters or underscores (_) in order to be filterable. This means if your data has a field called "Leg/hem length", to filter by this field you should rename to leg_hem_length before pushing to the Object Store.

Supported filters

The following types of filters are supported:

• Exact match
• Boolean operators
• Range filters
  • Inclusive and exclusive
  • Bounded and unbounded
• Sets
• Geographic range

Exact match

To filter search results by a field, give the field name and the value separated by a colon, i.e. {field name}:{value}. For example, to filter by color to only green values you would set filter_query=color:"green".

To filter by a value with spaces wrap the value in double quotes, i.e. filter_query=color:"dark green".

Boolean operators

Filters can be combined using AND, OR and NOT. So to search for items that are red or green, you would set filter_query=color:"green" OR color:"red".

Filters can also be combined across fields, so to search for items that are red and shoes you would provide filter_query=color:"red" AND category:"shoes". When providing multiple filters you may group them using parenthesis (). For example, to search for shoes that are red or green you would provide filter_query=(color:"green" OR color:"red") AND category:shoes.

Ranges

You can use interval notation to define the set to which a field's value must belong. Range filters are supported on the following field types:

• int
• float
• date

Your Filter Query will include two brackets with values separated by TO, where the type of bracket on either side indicates inclusivity (a square bracket) or exclusivity (a curly bracket), for that endpoint of the set. Omitting a value on either side will unbound that side of the expression.

For example, to search for shoes that cost $10 or less, you would provide: filter_query=price:[0 TO 10] AND category:shoes. Note that in this example, the price field must be indexed as an int or float type (e.g. 10 or 10.00), and not $10, which would be interpreted as a string.

Sets

Using the IN operator, a field can be matched against a set of literals, e.g. title: IN ["a" "b" "cd"] will match documents where title is either a, b or cd, but do so more efficiently than the alternative query title:"a" OR title:"b" OR title:"c" does. Example: filter_query=title: IN ["a" "b" "cd"].

Geographic range

We support filtering by geographic ranges on coordinate data. In order to filter on coordinates Objects must contain data with an object containing lat and lon fields. For example:

{
  "field_name": {
    "lat": 132.232,
    "lon": 987.567
  }
}

The syntax for filtering by geographic range is:

{field_name}:@{lat},{lon},{radius}

The radius value is measured in meters. The filter will apply a radius from the coordinates provided and include results in that radius' distance.

Example filter query:

# only include results within 10 meters from 39.0522,-120.2437
/search?query=test&filter_query=user_location:@39.0522,-120.2437,10

Errors when filtering

When constructing filter queries there are several types of errors that can occur. These errors result in HTTP 429 error codes, indicating that the query could not be applied. In this case the API will respond with HTTP 429 and a JSON containing a message with the error.

Example:

HTTP 429
{
  "detail": "Expected a valid string, boolean, integer, float, or datetime literal. Position: 44."
}

Examples

Always remember to URL encode the filter query before sending to the API.

Filter on a field name (e.g. color)

Assuming the object:

{
    "id": "123",
    "color": "blue"
}

Use the request: /search?filter_query=color:"blue"

Filter on multiple field values

Assuming the object:

{
    "id": "123",
    "color": "blue",
    "size": "M"
}

You can use "AND" and "OR" to filter on multiple fields. For example:

To filter on both values, use the request: /search?filter_query=color:"blue" AND size:"M"

To filter on either value, use the request: /search?filter_query=color:"blue" OR size:"M"