Skip to main content

Faceting Search Results

Use the facet_by parameter to specify which fields to use for generating facets (aggregated counts) in search results. Facets help users narrow down results by showing how many products match different values or ranges.

To discover which fields support faceting, list indexed fields and use entries with facetable: true (enable faceting when you configure indexable fields if needed).

Basic Usage​

Separate multiple fields with commas to facet by multiple attributes:

meta.search.nodes.name
extensions.products(Details).brand,meta.search.nodes.name

Numerical Range Faceting​

For numeric fields, define custom labeled ranges to group results.

Rating example:

extensions.products(Specification).rating(Average:[0, 3], Good:[3, 4], Great:[4, 5])

This creates three facet buckets: "Average" (0–3), "Good" (3–4), and "Great" (4–5).

Price example:

price.float_price(Budget:[0, 100], Mid-Range:[100, 500], Premium:[500, 1000], Luxury:[1000, ])
note

The last range [1000, ] includes all values 1000 and above.

Searching Facet Values​

Use facet_query to search within one facet's values, for example to offer a searchable brand filter. It takes the form field:text and returns only matching values, each with its count and a highlighted label:

curl "https://useast.api.elasticpath.com/v2/pcm/catalog/search?q=*&facet_by=extensions.products(Details).brand&facet_query=extensions.products(Details).brand:Eat" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
{
  "facet_counts": [
    {
      "field_name": "extensions.products(Details).brand",
      "counts": [
        { "value": "Eaton Wiring Devices", "count": 68, "highlighted": "<mark>Eat</mark>on Wiring Devices" },
        { "value": "Eaton Cooper Wiring", "count": 6, "highlighted": "<mark>Eat</mark>on Cooper Wiring" }
      ]
    }
  ]
}
  • The field must also be in facet_by, or the request is rejected with a 400.
  • Empty text after the colon behaves as if facet_query was not sent.
  • The label uses the profile's highlight tags.

Typo Tolerance​

facet_settings.query_num_typos on the search profile sets the maximum typos corrected in a facet query: 0, 1, or 2 (default). Short values are corrected less readily, whatever this allows. Product matching uses typo_tolerance instead.

{ "facet_settings": { "query_num_typos": 0 } }

Price Faceting in Segmented Catalogs​

Products can have multiple prices across different price books. The price used for faceting depends on the catalog rule configuration:

Catalog typePrice used for faceting
Non-segmented catalogsDefault catalog prices
Segmented catalogs with 0 rule price booksDefault catalog prices
Segmented catalogs with 1 rule price bookThe price book's prices by default. Set force_use_default_price_for_faceting_and_sorting to true in the search profile to use default catalog prices instead.
Segmented catalogs with >=2 rule price booksDefault catalog prices
note

Products in a segmented catalog can have prices defined across many price books. The above limitations only apply to price books referenced in catalog rules.

Price faceting limitations

Sales prices are not supported. Only base prices are used for faceting.

Ask External AI