Filters and Constraints

Filters and constraints allow you to control exactly which items from your catalog are eligible for a recommendation. In the Froomle platform, filtering is a collaborative process between your API request and our backend configuration.

If your use-case is not covered by the strategies outlined in this section, please reach out to our Customer Success team for assistance.

The Metadata Mapping Paradigm

Rather than defining complex query logic in the request (e.g., "WHERE price < 10 AND category = 'shoes'"), Froomle uses a mapping model:

  1. Request Fields: You pass specific fields and values in the list specification of your recommendation request.

  2. Item Metadata: Froomle compares these values against your synced item catalog.

  3. Backend Logic: The Froomle backend is configured to decide how to match them (e.g., "Must Match," "Exclude," or "Boost").

Using List Specification in Requests

To apply a filter, you add fields to the list specification object in your recommendation request. These fields serve as the "keys" for your filters.

{
  "channel" : "www-desktop",
  "device_id" : "the-cookie-id-123",
  "lists" : [ {
    "limit" : 5,
    "list_name" : "recommended_for_you",
    "list_size" : 5,
    "category": "electronics",
    "in_stock": true
  }, {
    "limit" : 5,
    "list_name" : "recommended_for_you",
    "list_size" : 5,
    "min_price": 30
  } ],
  "page_type" : "home"
}

In this example, the values "electronics", true, and 30 are passed to the Froomle Engine to be matched against item metadata. The Froomle backend is configured as follows:

  • Request field category "Matches" one of the values in the categories field of the item metadata.

  • Request field in_stock "Equals" the value item_attributes.stock > 0, derived from the item_attributes field of the item metadata.

  • Request field min_price "Less Than Or Equals" the item_attributes.price field of the item metadata.

Backend Configuration

While you provide the values in the request, the logic is defined in the Froomle backend. This keeps your frontend code simple and allows you to change business rules without redeploying your application.

Common configurations include: * Hard Inclusion: Only items matching the value are eligible. * Hard Exclusion: Items matching the value are removed from the pool. * Soft Boosting: Items matching the value are preferred but others can still be shown.

Available for Filtering

Not every field in your synced catalog is automatically usable for filtering. During the Item Synchronization phase, you must specify which metadata fields should be "available for filtering."

If you want to filter on a new field (e.g., brand_id), ensure it is included in your catalog sync and notify our Customer Success team to mark it as "available for filtering" in the backend.

Technical Specifications

Allowed match_types

The following match_types can be configured on the Froomle backend to compare request values against item metadata:

  • match: equal to

  • contains: substring check

  • starts_with: string prefix check

  • gt: greater than

  • gte: greater than or equal to

  • lt: less than

  • lte: less than or equal to

  • range: numeric value within a range [min, max]

Limit (optional)

A filter does not necessarily have to apply to every item in a module. You can specify a limit that defines the minimum or maximum number of recommendations to which the filter must or can apply. This is useful for "filling" a placement with a mix of specific categories and broader recommendations.

Business Constraints

While filters decide which items are eligible, Business Constraints define the required composition of the final result. They ensure that your business goals are met even when the AI algorithm might prefer other items.

Common use cases include: * Guaranteed Visibility: "At least 2 paid articles must be in the response." * Brand Policing: "Maximum 1 item from the 'Clearance' category per list." * Variety Control: "Exactly 3 different brands must be represented in the Top 5 results."

Constraints are configured in the Froomle backend, and apply to a list as a whole.

Dynamic Context

Filters are often "dynamic," meaning the value changes based on the user’s current context.

  • Same Category: Passing the category of the item currently being viewed.

  • User Group: Passing a segment ID (e.g., loyalty_tier_gold) to show exclusive products.

  • User Region: Passing the user’s region (e.g., BE-VLG) to show only local news or available products.

Best Practices

  • Keep Requests Clean: Only pass fields that are absolutely necessary for that specific placement.

  • Prefer Metadata over Hardcoding: Use attributes from your catalog for filtering rather than creating thousands of specialized modules.

  • Avoid Empty Sets: If you apply too many strict filters, you may end up with zero eligible items. Ensure your logic allows for a healthy inventory.

Related Topics