Facets

What a facet is

A facet is a filter panel next to the results: the brands with a product count each, price buckets, a price slider or a category tree. Every search response carries the facets of its profile, counted for that search. When the shopper clicks a value, the storefront sends it back as a filter and the next response shows the new results and counts.

A facet needs a field that is marked facetable in the index mapping. A facetable field can also be filtered by requests without further setup.

Index facets and profile facets

The facets usually live on the index, in one ordered list with their labels, limits and buckets. Every search profile shows that list unless it has facets of its own.

The index facets, in the order shoppers see them

• A profile that leaves out facets shows the index facets. Change them once and every such profile shows the change on its next search.
• A profile that sets facets, even to an empty list, shows its own list instead. Changes to the index facets do not reach it.

In the cabinet, open an index and then Facets. Add a facet per field, set its type and label, and drag the facets into the order shoppers see. Where they show lists the profiles that use the index facets and those that have their own. To give one profile its own facets, open the profile and change its Facets block.

PUT replaces the whole list. A facet on a field that is not facetable, or of a type the field cannot take, answers 400 FACETS_INVALID with one issue per facet.

curl -X PUT https://api.zaproo-search.com/v1/projects/$PROJECT_ID/indices/$INDEX_ID/facets \
  -H "Authorization: Bearer $ZS_KEY" -H "Content-Type: application/json" \
  -d '{"facets": [
    {"type": "hierarchy", "field": "category", "label": "Category"},
    {"type": "terms", "field": "brand", "label": "Brand", "limit": 30},
    {"type": "range", "field": "price", "label": "Price", "ranges": [{"to": 100}, {"from": 100, "to": 500}, {"from": 500}]},
    {"type": "stats", "field": "rating", "label": "Rating"}
  ]}'

Set the facets of the products index to: category tree, brand (30 values),
price buckets under 100, 100 to 500 and 500 and up, and a rating slider.

An index or a profile holds up to 50 facets.

Facet types

Every facet has a type, a facetable field and an optional label of up to 100 characters. The label comes back in the response, so the storefront can show it above the panel. Without one, the response has label: null.

{ "type": "terms", "field": "brand", "label": "Brand", "limit": 30, "order": "count" }

{ "type": "range", "field": "price", "ranges": [{ "to": 100 }, { "from": 100, "to": 500 }, { "from": 500 }] }

{ "type": "stats", "field": "price", "label": "Price" }

{ "type": "hierarchy", "field": "category", "label": "Category" }

How selection works

A request filter on a facet's field marks the matching values selected in the response. Two rules decide the counts.

Values in one facet add up

Values inside one facet combine with OR. A facet's counts ignore the request's filter on that facet's own field, so when a shopper ticks Samsung, the other brands keep their counts and the shopper can add LG as a second choice.

Different facets narrow each other

Filters on different fields combine with AND. Each facet's counts include the filters on every other field. After the shopper picks a price bucket, the brand counts show only products in that price range.

An example with three brands and a price facet:

Profile filters and exclusions work differently. They narrow the results and every facet count, so a facet never offers a value the profile would never show. Ranking rules that filter results do the same.

Facet results

Each facet in the response has type, field and label, plus:

• terms: items, each with key, count and selected.
• range: items, each with key (such as 100-500, or *-100 for an open side), from, to, count and selected.
• stats: count, min and max. min and max are null when no product has a value.
• hierarchy: level (0 for the top level), parent (the node whose children these are, or null) and items with full-path keys.

{ "type": "hierarchy", "field": "category", "label": "Category", "level": 1, "parent": "TV",
  "items": [{ "key": "TV>OLED", "count": 41, "selected": false }, { "key": "TV>QLED", "count": 28, "selected": false }] }

Hide empty facets

A profile's hideEmptyFacets setting, on by default, leaves out facets with nothing to pick for the current search: no values, every bucket at 0, or a stats count of 0. A facet the request filters on stays even when it is empty, so the shopper can still see and clear the selection.

Common mistakes

• A facet shows no values. The field is facetable in the mapping but the documents hold no value for it, or hold a value of another type. Check the field in a few documents.
• Filtering on a facet field answers FILTER_NOT_ALLOWED. The profile shows its own facets and that field is not among them. Add the facet, or add the field to the profile's extra filterable fields.
• A range bucket is never selected. The filter used lte or gt. Send gte with the bucket's from and lt with its to.
• Index facets do not show on a profile. The profile has facets of its own. Where they show on the Facets page lists it under the profiles with their own facets.