Configuring Searchable Attributes the Right Way

Searchable Attributes with Different Priorities

The order of attributes in the list of searchable attributes directly impacts search relevance. Attributes that are higher in the list are considered more relevant than attributes further down. Therefore, we recommend setting attributes higher in the searchable attributes list when their content is most relevant to your end users.

Imagine you have a movie database website, where users can search movies by title, actors, director, etc. Intuitively, you may be tempted to set the actors list with a higher priority than the director. Yet, consider the following dataset:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
  {
    "title": "Mystic River",
    "director": "Clint Eastwood",
    "actors": ["Sean Penn", "Tim Robbins", "Kevin Bacon", "Laurence Fishburne"]
  },
  {
    "title": "In the Line of Fire",
    "director": "Wolfgang Petersen",
    "actors": ["Clint Eastwood", "John Malkovich", "Renee Russo"]
  },
  {
    "title": "Invictus",
    "director": "Clint Eastwood",
    "actors": ["Morgan Freeman", "Matt Damon"]
  },
  {
    "title": "Million Dollar Baby",
    "director": "Clint Eastwood",
    "actors": ["Clint Eastwood", "Hilary Swank", "Morgan Freeman"]
  }
]

For a movie search, in most cases, setting the title as the first searchable attribute would make sense. However, what if someone typed “Clint Eastwood”? Would they primarily be looking for movies with or by Clint Eastwood (or both)? In other words, how should you prioritize the director and actors attributes?

By putting director first, movies that Clint Eastwood directed would come before those where he appeared in as actor. This may or may not be desirable. Another example makes it even clearer: imagine typing in “jane”. Do you want to first see movies with director Jane Campion, or actress Jane Fonda?

There’s no one-size-fits-all approach, and the strategy depends on your use case. Such cases underline the fact that defining a priority order in your searchable attributes isn’t trivial. It can vary depending on what your data is, how it’s structured, what your users usually search for, what they expect as results, etc.

Using the API

To make some attributes searchable, you need to use searchableAttributes during indexing time.

1
2
3
4
5
6
7
$index->setSettings([
  'searchableAttributes' => [
    "title",
    "director",
    "actor"
  ]
]);

1
2
3
4
5
6
7
index.set_settings({
  searchableAttributes: [
    'title',
    'director',
    'actor'
  ]
})

1
2
3
4
5
6
7
index.setSettings({
  searchableAttributes: [
    'title',
    'director',
    'actor'
  ]
});

1
2
3
4
5
6
7
index.set_settings({
    'searchableAttributes': [
        'title',
        'director',
        'actor'
    ]
})

1
2
3
4
5
6
7
index.setSettings([
  "searchableAttributes": [
    "title",
    "director",
    "actor"
  ]
])

1
2
3
4
5
6
7
8
9
index.setSettings(
  new JSONObject().put(
    "searchableAttributes",
    new JSONArray()
      .put("title")
      .put("director")
      .put("actor")
  )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string>
    {
      "title",
      "director",
      "actor"
    }
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
7
index.setSettings(
  new IndexSettings().setSearchableAttributes(Arrays.asList(
    "title",
    "director",
    "actor"
  ))
);

1
2
3
4
5
6
7
res, err := index.SetSettings(search.Settings{
  SearchableAttributes: opt.SearchableAttributes(
    "title",
    "director",
    "actor",
  ),
})

1
2
3
4
5
6
7
8
9
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    searchableAttributes = Some(Seq(
      SearchableAttributes.attributes("title")
      SearchableAttributes.attributes("director")
      SearchableAttributes.attribute("actor")
    ))
  )
}

1
2
3
4
5
6
7
8
9
val settings = settings {
    searchableAttributes {
        +"title"
        +"director"
        +"actor"
    }
}

index.setSettings(settings)

Using the Dashboard

You can also set your searchable attributes in your Algolia dashboard.

• Go to your dashboard and select your index.
• Click the Ranking tab.
• In the Searchable Attributes section, click the Add a searchable attribute button.
• Click on attributes in the dropdown, one after the other.
• Don’t forget to save your changes.

Searchable Attributes with the Same Priority

Sometimes, it doesn’t make sense to set an attribute before or after another, because you want them to be equally considered. Imagine another dataset, this time not only with records representing movies but also actors and directors:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
  {
    "movie_title": "John Wick",
    "cast": ["Keanu Reeves", "Michael Nyqvist", "Alfie Allen"]
  },
  {
    "actor_name": "John Cleese",
    "filmography": ["Monty Python and the Holy Grail", "Life of Brian", "Harry Potter and the Philosopher's Stone"]
  },
  {
    "director_name": "John Carpenter",
    "filmography": ["Halloween", "The Thing", "Escape from New York"]
  }
]

If someone typed “John”, it wouldn’t necessarily make more sense to show movies with “John” in the title than actors or directors named John. You may want to instead rely on other criteria, like popularity, to decide what comes first.

In this case, it would make sense to set movie_title, actor_name and director_name at the same level. This way, if someone typed “John”, all three records would be considered equal. The engine would go to the next searchable attribute to try and break the tie.

Using the API

To make some attributes searchable, you need to use searchableAttributes during indexing time.

1
2
3
4
5
6
7
$index->setSettings([
  'searchableAttributes' => [
    "movie_title,actor_name,director_name",
    "cast",
    "filmography"
  ]
]);

1
2
3
4
5
6
7
index.set_settings({
  searchableAttributes: [
    'movie_title,actor_name,director_name',
    'cast',
    'filmography'
  ]
})

1
2
3
4
5
6
7
index.setSettings({
  searchableAttributes: [
    'movie_title,actor_name,director_name',
    'cast',
    'filmography'
  ]
});

1
2
3
4
5
6
7
index.set_settings({
    'searchableAttributes': [
        'movie_title,actor_name,director_name',
        'cast',
        'filmography'
    ]
})

1
2
3
4
5
6
7
index.setSettings([
  "searchableAttributes": [
    "movie_title,actor_name,director_name",
    "cast",
    "filmography"
  ]
])

1
2
3
4
5
6
7
8
9
index.setSettings(
  new JSONObject().put(
    "searchableAttributes",
    new JSONArray()
      .put("movie_title,actor_name,director_name")
      .put("cast")
      .put("filmography")
  )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string>
    {
        "movie_title,actor_name,director_name",
        "cast",
        "filmography"
     }
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
7
index.setSettings(
  new IndexSettings().setSearchableAttributes(Arrays.asList(
    "movie_title,actor_name,director_name",
    "cast",
    "filmography"
  ))
);

1
2
3
4
5
6
7
res, err := index.SetSettings(search.Settings{
  SearchableAttributes: opt.SearchableAttributes(
    "movie_title,actor_name,director_name",
    "cast",
    "filmography",
  ),
})

1
2
3
4
5
6
7
8
9
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    searchableAttributes = Some(Seq(
      SearchableAttributes.attributes("movie_title", "actor_name", "director_name")
      SearchableAttributes.attributes("cast")
      SearchableAttributes.attribute("filmography")
    ))
  )
}

1
2
3
4
5
6
7
8
9
val settings = settings {
    searchableAttributes {
        +"movie_title,actor_name,director_name"
        +"cast"
        +"filmography"
    }
}

index.setSettings(settings)

Using the Dashboard

You can also set your searchable attributes in your Algolia dashboard.

• Go to your dashboard and select your index.
• Click the Ranking tab.
• In the Searchable Attributes section, click the Add a searchable attribute button.
• Type attributes directly in the input field as a comma-separated list (e.g., director,cast).
• Don’t forget to save your changes.

Understanding Word Position

By default, all searchable attributes are ordered. This means that matches at the beginning of an attribute are considered more important than in the middle or the end. If you specifically set them as unordered, the position of the match within the attribute doesn’t count.

Consider the following dataset:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
  {
    "title": "Avengers: Infinity War",
    "cast": ["Robert Downey Jr.", "Chris Hemsworth", "Mark Ruffalo", "Chris Evans", "Scarlett Johansson"]
  },
  {
    "title": "World War Z",
    "cast": ["Brad Pitt", "Mireille Enos", "Daniella Kertesz", "James Badge Dale", "Ludi Boeken"]
  },
  {
    "title": "War of the Worlds",
    "cast": ["Tom Cruise", "Dakota Fanning", "Justin Chatwin", "Miranda Otto", "Tim Robbins"]
  },
  {
    "title": "Thelma & Louise",
    "cast": ["Susan Sarandon", "Geena David", "Harvey Keitel", "Michael Madsen", "Brad Pitt"]
  }
]

If the user typed “war”, it wouldn’t make sense to return “War of the Worlds” before “World War Z”, or “World War Z” before “Avengers: Infinity War” only because the query happens to appear earlier in the title. The ranking would have to rely on another criterion like popularity or reviews. For that reason, title should be set as unordered.

However, things are different with the cast attribute. If the user typed “Brad Pitt”, chances are they would be interested in movies where Brad Pitt has a leading role, like “World War Z”, rather than small parts from his early career, like in “Thelma & Louise”. Therefore, keeping cast ordered makes more sense.

Using the API

You can set attributes as unordered when you make them searchable, using the searchableAttributes attribute during indexing time.

1
2
3
4
5
6
$index->setSettings([
  'searchableAttributes' => [
    "unordered(title)",
    "cast"
  ]
]);

1
2
3
4
5
6
index.set_settings({
  searchableAttributes: [
    'unordered(title)',
    'cast'
  ]
})

1
2
3
4
5
6
index.setSettings({
  searchableAttributes: [
    'unordered(title)',
    'cast'
  ]
});

1
2
3
4
5
6
index.set_settings({
    'searchableAttributes': [
        'unordered(title)',
        'cast'
    ]
})

1
2
3
4
5
6
index.setSettings([
  "searchableAttributes": [
    "unordered(title)",
    "cast"
  ]
])

1
2
3
4
5
6
7
8
index.setSettings(
  new JSONObject().put(
    "searchableAttributes",
    new JSONArray()
      .put("unordered(title)")
      .put("cast")
  )
);

1
2
3
4
5
6
7
8
9
10
11
12
13
IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string>
    {
        "unordered(title)",
        "cast"
     }
};

index.SetSettings(settings);

// Asynchronous
await index.SetSettingsAsync(settings);

1
2
3
4
5
6
index.setSettings(
  new IndexSettings().setSearchableAttributes(Arrays.asList(
    "unordered(title)",
    "cast"
  ))
);

1
2
3
4
5
6
res, err := index.SetSettings(search.Settings{
  SearchableAttributes: opt.SearchableAttributes(
    "unordered(title)",
    "cast",
  ),
})

1
2
3
4
5
6
7
8
client.execute {
  changeSettings of "myIndex" `with` IndexSettings(
    searchableAttributes = Some(Seq(
      SearchableAttributes.unordered("title")
      SearchableAttributes.attribute("cast")
    ))
  )
}

1
2
3
4
5
6
7
8
val settings = settings {
    searchableAttributes {
        +Unordered("title")
        +"cast"
    }
}

index.setSettings(settings)

Using the Dashboard

• Go to your dashboard and select your index.
• Click the Ranking tab.
• In the Searchable Attributes section, click the Add a searchable attribute button.
• Click on attributes in the dropdown one after the other, by order of importance.
• For each attribute, click the dropdown on the right and set them as ordered or unordered.
• Don’t forget to save your changes.

Successful Strategies

Setting searchable attributes is more an art than a science, and is highly dependent of your use case. There’s no magic formula that works for everyone. However, there are tips you can use to start off well.

Keeping as few searchable attributes as possible

As a rule of thumbs, the more searchable attributes, the noisier the search. It may be tempting to add as many searchable attributes as possible to get as many matches as you can. Yet, what it does is hurt search relevance by creating noise and littering good results with not so good ones.

Instead, you want to be conservative about what attributes you set as searchable, and focus on what your users usually search for. Some attributes, like image URLs or score on Rotten Tomatoes, shouldn’t be searchable because they don’t have textual value. Some other attributes, like the plot summary of a movie, might look interesting but could actually not be needed. How often do you find a movie by searching for the synopsis? Probably far less often than with the title or lead actors.

The same advice goes for the length of the attribute values. Let’s say you have an actors attribute in the records of a movies index. If this attribute contains the full cast, it’s less efficient than if it only had the leading roles, because that’s what most users would likely look for when searching by actor.

Properly setting attribute order

Knowing how to order your searchable attributes can be challenging, especially when you have many. One useful method is to compare them in pairs (each attribute with the previous one), and move them around accordingly. The process is similar to insertion sorting.

For example, let’s say you have the following attributes in the records of a movies index:

• director
• cast
• title
• genres
• plot_summary

Then, you would compare the first two: director and cast. If you think cast should come before director (e.g., you want to see movies with Clint Eastwood before movies directed by Clint Eastwood), you move cast to the first place. Then, you would compare director and title, and likely decide that the name of the movie is more important than the director. Therefore, you’d move it to the second place, and compare it with the previous one (cast) and decide whether you want to prioritize a match on an actor name or a movie title. If all records in your index represent movies, it may make sense to prioritize title, so you’d move it first. Then, because you wouldn’t have anymore attribute to compare title to, you’d move on to genres, etc.

The benefit is that you’re making a thorough, granular comparison of each attribute with the others, and considering your use case for every pair. This method is much more reliable than doing a global, intuitive sort by what seems more important.

Where to put filters?

In some cases, it’s useful to place filters above all other attributes. This might not seem intuitive at first, as attributes name or title usually seem to be the top item.

Let’s say you have a movies index, and in your records you’ve added a genre attribute with values like “crime” and “action”. There are many films that fall into these categories, but there are also a number of films whose titles and descriptions use these same words (e.g., “Crime Doesn’t Pay”, “Last Action Hero”).

In this case, you can make the decision that when a user types in words that are more like genres, it would be best to search inside the filter attributes before looking at the title. This guarantees returning all crime movies whenever someone types in “crime”, regardless of the title.

This is again the type of small decision when setting up searchable attributes that can have a significant impact on your results.

Changing your searchable attributes strategy

It’s important to be careful before you decide to change your searchable attributes strategy, because this affects your entire index. Don’t take decisions based on a single query. Instead, try to experiment with many different queries, if possible as close to what your end users search for. You can use your Algolia analytics to explore what your users search for, or your own data if you’re just starting out with Algolia.