# Filters and Constraints

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/filters-and-constraints.html)

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.

<a id="_the_metadata_mapping_paradigm"></a>

## 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").
    

<a id="_using_list_specification_in_requests"></a>

## 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.

> **IMPORTANT:**
> 
> Use the same name for the request filter key and the filterable item metadata field by default. If the names differ, Froomle must configure and confirm an explicit backend mapping before integration. Sending an unmapped request key does not filter the intended item metadata field.

```json
{
  "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.
    

<a id="_backend_configuration"></a>

## 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.
    

<a id="_available_for_filtering"></a>

## 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."

> **TIP:**
> 
> 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.

<a id="_technical_specifications"></a>

## Technical Specifications

<a id="_allowed_match_types"></a>

### 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]`
    

<a id="_limit_optional"></a>

### 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.

<a id="_business_constraints"></a>

## 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."

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

<a id="_dynamic_context"></a>

## 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.
    

<a id="_best_practices"></a>

## 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.
    

<a id="_related_topics"></a>

## Related Topics

-   [Item synchronization options](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/item-sync-options.html)
    
-   [Recommendation request model](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/recommendation-requests.html)
    
-   [Modules and placements](https://docs.froomle.com/froomle-doc-main/v2/guide/topics/modules-and-placements.html)