Skip to main content

Dynamic Facets

note

Dynamic Facets is an enterprise feature. Before you can use it, contact your Marqo representative to enable this feature on your account.

Dynamic Facets let you merchandise the facets shown alongside search and collection results. Instead of hard-coding a facets parameter on every request, you curate a single facet "superset" of allowed fields, then control which facets surface — and in what order — through merchandising rules. Marqo's algorithm fills in the rest dynamically based on engagement.

How It Works​

You first set the possible fields you want to be used in facets in Facet Superset — any rule can draw from this. Then you must create your rules. Each rule has a list of fields (Facet Fields) and a list of pins. You can pin any number of fields in your rule to any position explicitly. The unpinned fields will be dynamically ordered.

Dynamic ordering — Marqo ranks any unpinned fields based on engagement (e.g. four-week click counts) so the most useful facets float to the top automatically.

Rules can be set globally (apply to every search and collection), per search trigger, or per collection. Once configured, your storefront opts in by sending useDynamicFacets: true on the search request instead of a hand-crafted facets parameter.

Step 1: Enable the Feature Flag​

Reach out to your Marqo representative and ask them to enable the feature on your account. Until this is enabled, the Dynamic Facets panels will not appear in the merchandising console and the useDynamicFacets request parameter will be rejected.

Step 2: Configure the Facet Superset​

Navigate to Merchandising → Settings → Dynamic Facet Rules.

  1. Turn on the Dynamic Facet merchandising enabled switch at the top of the page.
  2. Use the Facet superset panel on the left to choose which fields are eligible to appear as facets.
  3. The Index fields panel on the right lists the fields Marqo has discovered from your index. Drag (or click) fields across to add them to the superset.
  4. If the field you want isn't shown on the right (e.g. a field that doesn't appear in the discovery sample, or a custom attribute), type the field name directly into the superset panel and pick a type.

Supported field types: text, numeric, array, boolean.

The superset is the single source of truth — every rule below can only reference fields that exist in this list. Removing a field from the superset removes it from every rule that references it.

tip

Keep your superset focused on fields shoppers actually filter by. Adding everything bloats the candidate pool and dilutes the dynamic ordering signal.

Step 3: Set Global Dynamic Facet Rules​

Navigate to Merchandising → Global Rules → Dynamic Facets.

This panel controls the default facets shown for every search and collection when useDynamicFacets: true is sent and no more specific rule matches.

  1. Add the facets you want to consider from the superset.
  2. For each facet you want locked to a specific position, pin it to a row number. Pinned facets always render in that slot.
  3. Leave any facets you want dynamically ordered as unpinned. Marqo will rank them by engagement and fill the remaining slots, in order, around the pins. The order you see the facets dynamically ordered in the UI is the same order they'll be returned in a search.

For example, a Global Rule with brand pinned to position 1, price pinned to position 3, and size, color, material left unpinned will always show:

  • Slot 1: brand
  • Slot 2: the most-engaged of material
  • Slot 3: price
  • Slots 4 & 5: the remaining unpinned fields in dynamic order

Step 4: Override Per Search Trigger​

Navigate to Merchandising → Search Rules → Dynamic Facets.

Use this when a specific query (or synonym group) needs a different facet selection than the global default. For example, a search for "running shoes" may need gender and size pinned at the top, while a search for "laptops" needs screen size and ram.

  1. Type the search trigger you want to override in the search bar.
  2. Add the facets (still drawn from the superset) and pin any that need fixed positions.

Anything not pinned remains in the dynamic order pool for that trigger.

Step 5: Override Per Collection​

Navigate to Merchandising → Collection Rules → Dynamic Facets.

Use this to override facets for a specific collection (e.g. a "Summer Sale" landing page that should always lead with discount and occasion).

  1. Select the collection you want to override from the dropdown.
  2. Add facets from the superset and pin positions as needed.

As with search overrides, anything you don't pin will be dynamically ordered.

Using Dynamic Facets at Search Time​

Once your rules are configured, opt in by setting useDynamicFacets to true on the search request:

{
  "q": "running shoes",
  "useDynamicFacets": true
}

Marqo applies the most specific rule that matches the request (collection override > search trigger override > global rule), assembles the merchandised facet configuration, and runs the search.

warning

useDynamicFacets and the facets parameter are mutually exclusive. A request that sets both will be rejected. When you opt in to useDynamicFacets, you are handing facet selection over to the merchandising layer and the dynamic algorithm — remove any facets payload your client used to send.

When to Use Each​

You want…Use
Different facets per query or collection without redeploying codeuseDynamicFacets: true + merchandising rules
The same facets on every request, fully controlled in codeThe standard facets parameter

Notes on Behaviour​

  • Rules are evaluated in order of specificity: a matching Collection Rule override wins over a matching Search Rule override, which in turn wins over the Global Rule.
  • Any facet referenced by a rule must exist in the superset. Removing a field from the superset removes it from every rule that referenced it.
  • Pinned positions are 1-based row numbers. Unpinned facets fill the remaining slots in dynamic-order rank.
  • Dynamic ordering ranks unpinned facets by engagement (default: clicks over the last four weeks). The most-engaged facets surface first.
  • If the Dynamic Facet merchandising enabled switch is off, requests with useDynamicFacets: true behave as if no facets were configured.