Filter expressions is a concept that allows users to define how result sets may be refined. Through defining rules around specific criteria: facets and group IDs, it is possible to include or exclude data that meets these conditions. They can be simple key-value mappings or complex boolean expressions combining multiple conditions using logical operators like AND, OR, and NOT.

Currently, filter expressions may be utilized when:

• Applying a pre_filter_expression when retrieving results from an API endpoint
• Defining a collection

Any configured facet or group ID in Constructor may be utilized within a filter expression.

Basic filter structure

A basic filter is defined as an object with the following structure:

Single value filter

{ "name": "filter_name", "value": "filter_value" }

This filter matches items where the specified filter field (filter_name) has the exact value (filter_value).

Example

{ "name": "group_id", "value": "electronics-group-id" }

Range filter

{ "name": "filter_name", "range": [min, max] }

This filter matches items where the specified filter field (filter_name) falls within the specified range (min to max). The min and max values are inclusive. Use "inf" for an unbounded upper limit and "-inf" for an unbounded lower limit.

Example

{ "name": "Price", "range": [50, 100] }

Composite filter expressions

Composite filter expressions allow combining multiple basic filters using logical operators. The following types of composite filter expressions are supported:

AND expression

{ "and": [expr1, expr2, expr3, ...] }

This matches items that satisfy all the given expressions (expr1, expr2, expr3, ...).

Example

{
    "and": [
        {
            "name": "group_id",
            "value": "electronics-group-id"
        },
        {
            "name": "Price",
            "range": [
                "-inf",
                200
            ]
        }
    ]
}

OR expression

{ "or": [expr1, expr2, expr3, ...] }

This matches items that satisfy at least one of the given expressions (expr1, expr2, expr3, ...).

Example

{
    "or": [
        {
            "name": "Type",
            "value": "Laptop"
        },
        {
            "name": "Type",
            "value": "Desktop"
        }
    ]
}

NOT expression

{ "not": expr }

This matches items that do not satisfy the given expression (expr).

Example

{
    "not": {
        "name": "Price",
        "range": [
            800,
            "inf"
        ]
    }
}

Nesting and limits

• Nesting: Filter expressions can be nested up to a maximum depth of 5 levels. This allows for creating complex logical structures to refine search results.
• Filters count: A filter expression cannot contain more than 150 filters in total. This includes all nested filters.

Example

{
  "or": [
    {
      "and": [
        { "name": "group_id", "value": "electronics-group-id" },
        { "name": "Price", "range": ["-inf", 200] }
      ]
    },
    {
      "and": [
        { "name": "Type", "value": "Laptop" },
        { "not": { "name": "Price", "range": [800, "inf"] } }
      ]
    }
  ]
}