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 facet you added to your index, for example, color and size, retrieve a list of facet values, for example, blue, red, small, or large for records matching the current search query. For each facet value, the response also contains the number of matching records with that facet value.

Usage notes

  • You need to add all attributes you want to use for faceting to the attributesForFaceting index setting.

  • Faceting doesn’t filter the search results. It’s a setting for the search engine to allow you to filter the results at search time with the filters parameter.

  • By default, no facets are retrieved. The same is true if you set facets to an empty list: facets: [].

  • You can retrieve all facets with the wildcard * character: facets: ['*'].

  • By default, facet values are sorted by frequency. You can change this with the sortFacetValuesBy parameter.

Approximate facet counts and facet values

The response can contain two additional parameters:

  • exhaustiveFacetsCount: if the number of hits for a query is high, the facet count may be approximate. The response contains exhaustiveFacetsCount: true if the facet count is exact.

  • exhaustiveFacetValues: by default, up to 100 facet values are retrieved per facet. The response contains exhaustiveFacetValues: false if not all facet values are retrieved.

    You can increase this number by increasing the maxValuesPerFacet setting to a maximum of 1,000.

  • Facet values are truncated to 1,000 characters.

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 attributes must be added to the attributesForFaceting index setting before searching.

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 (exhaustive).

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