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

Can be used in these methods:

About this parameter

The complete list of attributes that will be used for faceting.

Use this setting for 2 reasons:

  • to turn an attribute into a facet
  • to make any string attribute filterable.

By default, your index comes with no categories. By designating an attribute as a facet, this enables Algolia to compute a set of possible values that can later be used to filter results or display these categories. You can also get a count of records that match those values.

Usage notes

  • This setting enables both faceting and filtering.

  • Default: If not specified or empty, no attribute will be faceted.

  • Nested Attributes: All attributes can be used for faceting, even when nested. For example, authors.mainAuthor can be used for faceting. Here the faceting will be applied only on mainAuthor.

You should not include colons (:) in attribute names that you want to use for faceting, because the filters syntax relies on that character as a delimiter.


  • filterOnly: Defines an attribute as filterable only and not facetable.

    If you only need the filtering feature, you can take advantage of filterOnly which will reduce the index size and improve the speed of the search.

    You cannot define an attribute as both ‘filterOnly’ and ‘searchable’. The following therefore is not doable: filterOnly(searchable(attributeName)).

  • searchable: Defines an attribute as searchable.

    If you want to search for values of a given facet (using the Search for facet values method) you need to specify searchable.

    You cannot define an attribute as both ‘searchable’ and ‘filterOnly’. The following therefore is not doable: searchable(filterOnly(attributeName)).


Set attributesForFaceting

The following example shows how to:

  • make some attributes usable for faceting
  • make an attribute only filterable
  • make an attribute usable with Search for facet values
  'attributesForFaceting' => [
Did you find this page helpful?