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 to use for faceting.

Use this setting for two reasons:

  • To turn an attribute into a facet. This is a prerequisite for faceted search.
  • To make any string attribute filterable.

There’s no limit to the number of attributes in the list, but having many attributes slows down calls to getSettings. This can make the Algolia dashboard slower and less responsive.

By default, your index doesn’t have categories. Designating an attribute as a facet 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.

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

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.

Don’t include colons (:) in attribute names that you want to use for faceting because the filters syntax relies on that character as a delimiter.



Defines an attribute as filterable only and not facetable.

If you only need the filtering feature, use the filterOnly modifier to reduce the index size and improve the search speed.

You can’t define an attribute as filterOnly and searchable. The following, therefore, isn’t possible: filterOnly(searchable(attributeName)).


Defines an attribute as searchable.

If you want to search for values of a given facet (using the Search for facet values method), use the searchable modifier.

You can’t define an attribute as searchable and filterOnly. The following, therefore, isn’t possible: searchable(filterOnly(attributeName)).


Computes the facet counts of this attribute after distinct has been applied.

If you use the distinct parameter to deduplicate or group record variants by the same attribute, such as brand, it’s often best to compute the facet count after distinct.

It can be helpful to combine the afterDistinct and searchable modifiers for an attribute, if you want to search for facet values. For example: afterDistinct(searchable(attributeName)).

Note that if you use both the afterDistinct modifier and the facetingAfterDistinct search parameter, then the latter will take precedence and facetingAfterDistinct will be applied to all facets of the query.


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?