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

Attributes to use for facets.

During index creation, you chose attributes to help users filter and facet search results. Faceting lets you display categories or counts of values in the UI, while filtering restricts which records are shown based on specific attribute values. For example, in a book index, typical faceting attributes include author and genre.

To enable an attribute for filtering or showing as a facet in results, you must add it to attributesForFaceting.

Usage notes

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

Specify an attribute with attributesForFaceting to enable faceting and filtering:

Faceting lets you use attributes in facets
Filtering lets you use attributes in filters, facetFilters, and optionalFilters

You can use any attribute for faceting, even if it’s nested. For example, you can facet on a nested attribute like authors.mainAuthor. This will only apply the faceting logic to the mainAuthor nested attribute, not the entire authors attribute. Attribute names are case-sensitive.

Don’t use colons (:) in attribute names used for faceting. Colons are reserved for Algolia’s filters syntax.

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 equivalent to setting an attribute as not searchable in the dashboard.

While there’s no limit to the number of attributes, adding too many attributes can slow down calls to getSettings and reduce the responsiveness of Algolia’s dashboard.

Modifiers

filterOnly

Use this modifier if you want to use an attribute for filtering (not faceting). For example, use it for attributes like isInStock which you might not want to expose as a facet in the UI.

This saves space in your index and improves performance.

You can’t combine filterOnly and searchable on the same attribute. These modifiers are mutually exclusive. The following, therefore, isn’t possible: filterOnly(searchable(attributeName)).

searchable

Use this modifier if you want users to search within a facet’s values. For example, typing a name in a long list of authors.

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

afterDistinct

Use this modifier when you’ve enabled distinct to group similar records (such as product color variants). To ensure accurate facet counts, the modifier ensures they’re calculated after such duplicates are removed.

Only use this on attributes common across all records with the same distinct key.

If you also set facetingAfterDistinct to true in your query, that setting overrides afterDistinct.

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`

In the following example:

Copy
{
"attributesForFaceting": [
  "author",
  "edition",
  "category",
  "publisher",
  "filterOnly(isbn)",
  "searchable(edition)",
  "searchable(publisher)"
]
}

author, edition, category, and publisher: available for both faceting and filtering.
isbn: only available for filtering.
edition and publisher: users can search inside these facet values.

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))",
    ))
  )
}

Did you find this page helpful?