List-attribute filtering for recommendations

List-attribute filtering for recommendations lets you filter products using multi-value attributes like tags, genres, promotions, or regions. This unlocks essential merchandising strategies: run multi-promotional campaigns, build tag-based collections, and ensure regional relevance—all without creating multiple recommendation models.

This article explains what list-attribute filtering is, when to use each operator, and how to configure filters. For implementation examples, see list-attribute filtering use cases.

📘

Note

List-attribute filtering is available for catalogs powered by the new schema-based infrastructure, created after version 1.302. Contact your Customer Success Manager to verify your catalog supports this feature.

List-attribute filtering benefits

• Run multi-promotional campaigns: Feature products from several active promotions simultaneously.
• Leverage existing product tags: Use Shopify tags or custom taxonomies to build themed collections.
• Create curated content experiences: Build genre-based collections that match specific themes.
• Ensure regional relevance: Show only products available in specific markets.

Prerequisites

Before using list-attribute filtering:

• Use a catalog powered by the new schema-based catalog infrastructure. On unified setups, this means a catalog created from Data hub item collections.
• Configure list attributes as searchable fields in your catalog settings.
• Ensure your product data includes properly formatted list attributes (arrays of strings or numbers).

Set up list-attribute filtering

1. Navigate to Campaigns > Recommendations and open your recommendation model.
2. In the Design tab, scroll to 1. Catalog.
3. Select your catalog.

4. Click + Add another item filter.
5. Configure your filter:
   • First dropdown: Select the list attribute (tags_list, genres_list, promo_list).
   • Second dropdown: Choose operator (any item or contains all).
   • Third dropdown: Select condition (equals or in).
   • Input field: Enter your value(s).
6. Click Save to activate your filters.

Test your filters: Use the Test tab to verify filters work correctly before deploying to production.

Understanding list filtering operators

Any item operator

Matches products where at least one value in the list meets your criteria.

When to use: Campaigns with multiple promotions, tag-based collections, genre groupings, regional targeting, or brand portfolios.

Example: Using any item, filter products where promo_list contains any of ["Summer_Sale", "Clearance", "New_Arrivals"]. Products tagged with "Summer_Sale" will match, as will products tagged with "Clearance" or "New_Arrivals".

Contains all operator

Matches products only when the list contains every specified value.

When to use: Compliance requirements, multi-certification standards, or products needing multiple specific attributes.

Example: Using contains all, filter products where certifications_list contains all ["ISO_9001", "CE_certified"]. Only products with both certifications will match. Products with just one certification are excluded.

Key difference: Any item needs at least one match; contains all requires every specified value.

See list-attribute filtering use cases for detailed business scenarios.

📘

Note

To filter recommendations differently for each customer (like showing products in their preferred size or based on individual preferences), use dynamic filters in your recommendation requests. Learn more about list-type operators for dynamic filtering.

Performance best practices

Recommended limits:

• List length: Under 100 items per product
• Operator values: Maximum 100 values for "in" or "contains all"
• Number of filters: Up to 20 simultaneous list filters

Exceeding these soft limits may increase recommendation response time during high-traffic periods.

Optimization tips:

• Use your most restrictive filters first.
• Combine related criteria instead of creating many separate filters.
• Test response times in the Test tab after adding filters.

Limitations

Schema-based catalogs only: List-attribute filtering is available only for catalogs using the new schema-based catalog infrastructure. Legacy catalogs are not supported.

List replacement required: Must replace entire lists during data ingestion; can't append individual items.

Searchable fields required: Only searchable attributes can be used in list filters.