How to declare attributes for faceting with the API

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

To do so, you first need to declare attributes genre and author as attributesForFaceting:

Copy

1
2
3
4
5
6
$index->setSettings([
  'attributesForFaceting' => [
    "category",
    "author"
  ]
]);

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
IndexSettings settings = new IndexSettings
{
    AttributesForFaceting = new List<string>
    {
      "category",
      "author"
    }
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

Sometimes, you may have many facet values. For instance, if you have many books in your index, you may also have plenty of different authors. The engine can’t return more than 1,000 values per facet, so if you have more, you may want to let your users search for them. You can achieve this by using the searchable modifier.

Copy

1
2
3
4
5
6
$index->setSettings([
  'attributesForFaceting' => [
    "category",
    "searchable(author)"
  ]
]);

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

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

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

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
7
8
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    attributesForFaceting = Some(Seq(
      "category",
      "searchable(author)",
    ))
  )
}

If you only need the filtering feature, take advantage of filterOnly to reduce the index size and improve search speed. Imagine you want to automatically filter what genre the users can search based on what section of your website they’re on without displaying genres as clickable filters. In this case, you only need filtering capabilities.

Copy

1
2
3
4
5
6
$index->setSettings([
  'attributesForFaceting' => [
    "filterOnly(category)",
    "author"
  ]
]);

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

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

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

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
7
8
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    attributesForFaceting = Some(Seq(
      "filterOnly(category)",
      "author",
    ))
  )
}

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.

If you prefer to use Algolia’s dashboard to declare attributes, read the Configuring faceting guide.

Did you find this page helpful?