API Reference / API Parameters / facets
Type: list of strings
Engine default: [] (no facets retrieved)
Parameter syntax
'facets' => [
  'attribute',
  ...
]

Can be used in these methods:

About this parameter

Retrieve facets, their facet values, and the number of matching facet values.

For each specified facet (for example, color and size) in your index:

  • Retrieve a list of facet values (for example, blue, red, small, large) for records matching the current query
  • For each facet value, the response also contains the number of matching records for that facet value

Retrieve all facets from your index with the wildcard * character. For example, facets: ['*'].

Usage notes

  • Add all attributes you want to use for faceting with attributesForFaceting.
  • Faceting itself doesn’t filter the search results: you filter results at search time with the filters parameter.
  • By default, or if you set facets to an empty list (facets: []), no facets are retrieved.

Approximate facet counts and facet values

  • By default, facet values are sorted by frequency: change this with the sortFacetValuesBy parameter.
  • Facet values are truncated to 1,000 characters.
  • The response can have two additional parameters (in the exhaustive object):

    • facetsCount: the field facetsCount is true if the facet count is exact. For queries with many hits, the facet count may be approximate.
    • facetValues: by default, up to 100 facet values are retrieved per facet. The exhaustive object contains facetValues: false if not all facet values are retrieved. Increase this limit with maxValuesPerFacet (to a maximum of 1,000).

Examples

Retrieve only some facets

The following example searches for “query” and retrieves the facets and facet values for the author and category attributes. Both must have previously been declared as attributes for faceting with the API or dashboard.

1
2
3
$results = $index->search('query', [
  'facets' => ['category', 'author']
]);

The example response shows three matches for “Jhon” in the author facet and one match in the category facet for “Classical”.

The facet count is exact.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "facets": {
    "author": {
      "Jhon": 3,
    },
    "category": {
      "Classical": 1,
    }
  },
  "exhaustiveFacetsCount": true,
  "exhaustive": {
    "facetsCount": true
  },
  "hits": {...},
}
Did you find this page helpful?