API Reference / API Parameters / attributesForFaceting

Nov 25, 2021

attributesForFaceting

Type: list of strings

Engine default: [] (no facets)

Parameter syntax

'attributesForFaceting' => [
  'attribute1',
  'filterOnly(attribute2)',
  'searchable(attribute3)',
  'afterDistinct(attribute4)',
  'afterDistinct(searchable(attribute5))'
]

attributesForFaceting: [
  'attribute1',
  'filterOnly(attribute2)',
  'searchable(attribute3)',
  'afterDistinct(attribute4)',
  'afterDistinct(searchable(attribute5))'
]

attributesForFaceting: [
  'attribute1',
  'filterOnly(attribute2)',
  'searchable(attribute3)',
  'afterDistinct(attribute4)',
  'afterDistinct(searchable(attribute5))'
]

'attributesForFaceting': [
  'attribute1',
  'filterOnly(attribute2)',
  'searchable(attribute3)',
  'afterDistinct(attribute4)',
  'afterDistinct(searchable(attribute5))'
]

attributesForFaceting = [
  "attribute1",
  .filterOnly("attribute2"),
  .searchable("attribute3")
]

attributesForFaceting {
    +"attribute1"
    +FilterOnly("attribute2")
    +Searchable("attribute3")
}

IndexSettings settings = new IndexSettings
{
  AttributesForFaceting = new List<string>
  {
    "attribute1",
    "filterOnly(attribute2)",
    "searchable(attribute3)",
    "afterDistinct(attribute4)",
    "afterDistinct(searchable(attribute5))"
  }
};

new IndexSettings().setAttributesForFaceting(Arrays.asList(
  "attribute1",
  "filterOnly(attribute2)",
  "searchable(attribute3)",
  "afterDistinct(attribute4)",
  "afterDistinct(searchable(attribute5))"
))

opt.AttributesForFaceting(
  "attribute1",
  "filterOnly(attribute2)",
  "searchable(attribute3)",
  "afterDistinct(attribute4)",
  "afterDistinct(searchable(attribute5))",
)

attributesForFaceting = Some(Seq(
  "attribute1",
  "filterOnly(attribute2)",
  "searchable(attribute3)",
  "afterDistinct(attribute4)",
  "afterDistinct(searchable(attribute5))"
))

Can be used in these methods:
setSettings set_settings setSettings set_settings setSettings setSettings SetSettings setSettings SetSettings setSettings

See code examples

About this parameter

List of attributes to use for faceting.

Algolia lets you create categories based on specific attributes so users can filter search results by those categories. For example, if you have an index of books, you could categorize them by author and genre. This allows users to filter search results by their favorite author or discover new genres.

To enable this categorization, declare your attributes as attributesForFaceting.

Guides How to declare attributes for faceting with the API

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.

Usage notes

If no attribute is specified, no attributes will be faceted.

Specify an attribute with attributesForFaceting to enable faceting and filtering:

Faceting allows you to use attributes inside facets
Filtering allows you to use attributes inside filters, facetFilters, and optionalFilters

All attributes can be used for faceting, even when nested. For example, authors.mainAuthor can be used for faceting but will only be applied on mainAuthor. Attribute names are case-sensitive.

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

Use modifiers to change the behavior of faceted attributes. If you don’t specify a modifier, an attribute will just be used as a facet. This is the equivalent of setting an attribute as not searchable on the dashboard.

Modifiers

filterOnly

Only define this modifier if you want to use an attribute for filtering (not faceting).

This modifier reduces index size and improves search speed.

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

searchable

Only define this modifier if you want users to search for facet values.

It can be helpful to combine the afterDistinct and searchable modifiers to search for facet values (using the Search for facet values method), to ensure accurate facet counts. For example, afterDistinct(searchable(attributeName)).

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

afterDistinct

Computes the facet counts of an attribue after distinct has been applied.

If you’re using distinct to deduplicate or group record variants by the same attribute, the afterDistinct modifier ensures accurate facet counts.

For proper values listing and consistent facet counts, you can only use the afterDistinct modifier on facet attributes shared between all the records sharing a common distinct key.

If you use the afterDistinct modifier and set facetingAfterDistinct to true, the latter takes precedence and applies to all the query’s facets.

It can be helpful to combine the afterDistinct and searchable modifiers to search for facet values (using the Search for facet values method), For example, afterDistinct(searchable(attributeName)).

Examples

Set attributesForFaceting

The following example shows how to:

Define some attributes as usable for faceting: author, edition, category, and publisher
Set the isbn attribute as only usable for filtering
Allow the edition and publisher facet values to be searchable.

Copy

1
2
3
4
5
6
7
8
9
$index->setSettings([
  'attributesForFaceting' => [
    "author",
    "filterOnly(isbn)",
    "searchable(edition)",
    "afterDistinct(category)",
    "afterDistinct(searchable(publisher))"
  ]
]);

1
2
3
4
5
6
7
8
9
index.set_settings({
  attributesForFaceting: [
    'author',
    'filterOnly(isbn)',
    'searchable(edition)',
    'afterDistinct(category)',
    'afterDistinct(searchable(publisher))'
  ]
})

1
2
3
4
5
6
7
8
9
10
11
index.setSettings({
  attributesForFaceting: [
    'author',
    'filterOnly(isbn)',
    'searchable(edition)',
    'afterDistinct(category)',
    'afterDistinct(searchable(publisher))'
  ]
}).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
index.set_settings({
    'attributesForFaceting': [
        'author',
        'filterOnly(isbn)',
        'searchable(edition)',
        'afterDistinct(category)',
        'afterDistinct(searchable(publisher))'
    ]
})

1
2
3
4
5
6
7
8
9
10
11
12
let settings = Settings()
  .set(\.attributesForFaceting, to: [
    "author",
    .filterOnly("isbn"),
    .searchable("edition")
  ])

index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
val settings = settings {
    attributesForFaceting {
        +"author"
        +FilterOnly("isbn")
        +Searchable("edition")
    }
}

index.setSettings(settings)

1
2
3
4
5
6
7
8
9
10
11
IndexSettings settings = new IndexSettings
{
  AttributesForFaceting = new List<string>
  {
    "author",
    "filterOnly(isbn)",
    "searchable(edition)",
    "afterDistinct(category)",
    "afterDistinct(searchable(publisher))"
  }
};

1
2
3
4
5
6
7
8
9
index.setSettings(
  new IndexSettings().setAttributesForFaceting(Arrays.asList(
    "author",
    "filterOnly(isbn)",
    "searchable(edition)",
    "afterDistinct(category)",
    "afterDistinct(searchable(publisher))"
  ))
);

1
2
3
4
5
6
7
8
9
res, err := index.SetSettings(search.Settings{
  AttributesForFaceting: opt.AttributesForFaceting(
    "author",
    "filterOnly(isbn)",
    "searchable(edition)",
    "afterDistinct(category)",
    "afterDistinct(searchable(publisher))",
  ),
})

1
2
3
4
5
6
7
8
9
10
11
client.execute {
  setSettings of "myIndex" `with` IndexSettings(
    attributesForFaceting = Some(Seq(
      "author",
      "filterOnly(isbn)",
      "searchable(edition)",
      "afterDistinct(category)",
      "afterDistinct(searchable(publisher))",
    ))
  )
}