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

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.

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

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.

Modifiers

filterOnly

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

searchable

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

afterDistinct

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.

Examples

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

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 {
  changeSettings of "myIndex" `with` IndexSettings(
    attributesForFaceting = Some(Seq(
      "author",
      "filterOnly(isbn)",
      "searchable(edition)",
      "afterDistinct(category)",
      "afterDistinct(searchable(publisher))",
    ))
  )
}