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.

Within a facet you can also curate the values themselves, pinning values to the front and grouping several values under one label. See Merchandising facet values.

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.

useDynamicFacets is never rejected for being unavailable. The parameter is always accepted, and it always hands facet selection to the merchandising layer. If the feature is not enabled, or the switch in Step 2 is off, or no rule resolves for the request, the response simply carries no facets and returns 200. The facets configured for your index are not used as a fallback, so a storefront that sends useDynamicFacets: true before the feature is live shows no facets at all rather than an error.

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

A search rule also covers searches made inside a collection, because those are resolved as searches rather than as collection browses. If the query belongs to a synonym group, author the rule against the group's parent phrase. Both points are explained in Which rule applies.

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.

A collection rule applies when the shopper is browsing the collection. As soon as they search within it, the request is resolved against your Search Rules instead.

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 derives one trigger from the request, looks for an override on that trigger, and falls back to the Global Rule when there is none. See Which rule applies below.

warning

useDynamicFacets and the facets parameter are mutually exclusive. A request that sets both is rejected with 422 and the message 'useDynamicFacets' and 'facets' cannot both be set. When you opt in to useDynamicFacets, you are handing facet selection over to the merchandising layer and the dynamic algorithm, so remove any facets payload your client used to send.

Which Rule Applies​

There is no cascade. Marqo derives exactly one trigger from the request, looks up the override for that trigger, and uses the Global Rule if no override exists.

RequestTrigger usedRule consulted
/searchThe querySearch Rule for that query, else Global
/collections with no q (a browse)The collection nameCollection Rule for that collection, else Global
/collections with a q (search within a collection)The querySearch Rule for that query, else Global

The third row is the one that surprises people. A search inside a collection is treated as a search, so a Collection Rule never applies to it. If shoppers search within a collection and you need different facets there, author a Search Rule for the queries they use.

Two more rules of thumb:

  • An override with no facets in it is treated as absent, and the Global Rule applies instead.
  • Image queries never match a rule. A search whose q is an image URL or data URL falls through to the Global Rule.

Triggers Match the Substituted Query​

Synonym substitution runs before facet rules are resolved. If a shopper's query is a child term in a synonym group, the trigger Marqo looks up is the group's parent phrase, not what the shopper typed.

Author Search Rules against the parent phrase. A rule created for a child term never fires, because by the time the rule is resolved the query has already been replaced. See Synonyms and Taxonomy Tools.

Trigger matching is otherwise exact, after Unicode normalisation, lowercasing and trimming.

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

Merchandising Facet Values​

Everything above orders the facet fields. You can also curate the values inside a bucketed facet: pin values to the front, and group several raw values under one label. Both are available on text, array and boolean facets. Numeric facets return a statistics object rather than value buckets, so value rules do not apply to them and are ignored.

Value rules change what your storefront receives, so it is worth knowing exactly what Marqo does.

Value Pins​

Pinned values are moved to the front of that field's buckets, in the order you pinned them, followed by the remaining values in Marqo's own order. Counts are never changed.

A pinned value that has no bucket in this response is skipped rather than invented, so a value with no matching products does not appear as an empty option.

Value Groups​

A value group folds several raw values into a single bucket labelled with a name you choose. The label's count is the sum of the member counts, and the label takes the position of the first member that appeared in Marqo's order.

For example, grouping King, California King and Split King under the label King Sizes turns three options into one:

{
  "facets": {
    "size": {
      "King Sizes": { "count": 128 },
      "Queen": { "count": 96 }
    }
  }
}

A group whose members all have zero results is not synthesised. If a raw value already carries the same name as the label, it folds into the label bucket rather than appearing twice. Labels can themselves be pinned, because grouping is applied before value pins.

Filtering on a Group Label​

Your storefront filters on the label exactly as it would on a raw value. Marqo rewrites the clause into the group's members before running the search, so this request:

{
  "q": "bedding",
  "useDynamicFacets": true,
  "filter": "size:(King Sizes)"
}

is executed as size:(King) OR size:(California King) OR size:(Split King) OR size:(King Sizes). The field:value, field:(value) and field IN (...) forms are all recognised. The rewrite is structural, so a group label appearing inside another field's value is left alone, and a filter Marqo cannot parse is passed through untouched.

How Counts Respond to Filters​

Facet counts behave in one of two modes, set for your index by your Marqo representative.

ModeBehaviour
defaultEach field's counts are recalculated against the filters applied to the other fields, so the numbers update as a shopper narrows down.
staticThe terms in the request's own filter are excluded from every field, so counts stay at the page's unfiltered baseline and do not move as filters are applied.

Static mode excludes only the filter your client sent. Filters that Marqo adds itself, such as the collection scoping term, your index's configured filter and any merchandising rule filters, always remain in force, because merchandising curation defines the base set the counts describe.

note

Two known limitations, both inherited from how facet buckets are represented.

  • On an array field, a document carrying more than one member of the same group is counted once per member, so a group's summed count can exceed the number of matching products.
  • Values that look like whole numbers, such as 8 or 10, cannot be reordered by a value pin. This affects numeric-looking text values and group labels alike.

Notes on Behaviour​

  • Exactly one rule applies per request: the override for the request's trigger, or the Global Rule. See Which rule applies.
  • 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.
  • Marqo's dynamic ordering only scores fields whose coverage clears an eligibility threshold. Fields below it keep their input order, which is alphabetical by field name.
  • If the Dynamic Facet merchandising enabled switch is off, requests with useDynamicFacets: true behave as if no facets were configured. No error is returned.
  • Rule changes take a few minutes to reach live traffic after you publish them.