Configuring Searchable Attributes the Right Way

Setting searchable attributes is one of the most important aspects of configuring your search, and one of the first steps you need to take. It goes much further than telling Algolia which attributes to search. It also defines which ones to look at first and what strategy to adopt when doing so. A small change in how you set searchable attributes could lead to entirely different results. For that reason, it’s crucial to understand how it works and take the time to set it correctly.

Besides deciding which attributes Algolia should search into, there are two aspects you can control with searchable attributes:

• the relative importance of each attribute
• whether the position of the match in the attribute matters

Searchable attributes with different priorities

The order of attributes in the list of searchable attributes directly impacts search relevance. The engine considers attributes that are higher in the list more relevant than attributes further down. For that reason, you should set 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, setting the title as the first searchable attribute would make sense. But what if someone searched for “Clint Eastwood”? Would they primarily be looking for movies with Clint Eastwood, by Clint Eastwood, or both? In other words, how should you rank 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 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
8
9
index.setSettings({
  searchableAttributes: [
    'title',
    'director',
    'actor'
  ]
}).then(() => {
  // done
});

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.

1. Navigate to the Indices page of the dashboard and select your index.
2. Click the Configuration tab.
3. In the Searchable Attributes section, click the Add a searchable attribute button.
4. Add attributes you want to make searchable one after the other, by order of importance.
5. 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 makes sense to set movie_title, actor_name and director_name at the same level. This way, if someone types “John”, the engine considers all three records equal in the attribute ranking criterion. The engine would go to the next ranking criterion to try and break the tie.

To consider all attributes with the same-priority equivalently, same-priority attributes are always unordered.

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
8
9
index.setSettings({
  searchableAttributes: [
    'movie_title,actor_name,director_name',
    'cast',
    'filmography'
  ]
}).then(() => {
  // done
});

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.

1. Navigate to the Indices page of the dashboard and select your index.
2. Click the Configuration tab.
3. In the Searchable Attributes section, click the Add a searchable attribute button.
4. Type attributes directly in the input field as a comma-separated list—for example, director,cast.
5. Don’t forget to save your changes.

Understanding word position

By default, all searchable attributes are ordered. That means the engine considers matches at the beginning of an attribute more important than matches in the middle or the end. When an attribute is ordered, the earlier a match occurs in an attribute, the higher the engine ranks it. If you specifically set searchable attributes as unordered, the position of the match within the attribute doesn’t impact ranking.

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": "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": "Lost in Translation",
    "cast": ["Scarlett Johansson", "Bill Murray", "Akiko Takeshita"]
  }
  {
    "title": "North",
    "cast": ["Elijah Wood", "Jason Alexander", "Julia Louis-Dreyfus", "Marc Shaiman", "Scarlett Johansson"]
  }
]

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

Things are different with the cast attribute. If the user typed “Scarlett Johansson,” chances are they would be more interested in movies where Scarlett Johansson has a leading role than movies where she played small parts early in her career. Assuming that the order of actors and actresses in the cast attribute reflects role size, 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
7
8
index.setSettings({
  searchableAttributes: [
    'unordered(title)',
    'cast'
  ]
}).then(() => {
  // done
});

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

1. Navigate to the Indices page of the dashboard and select your index.
2. Click the Configuration tab.
3. Go to the Searchable Attributes section. If not done so already, add attributes in order of importance.
4. For each searchable attribute, consider whether it should be ordered or unordered. If unordered, click the dropdown on the right and select unordered.
5. 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 tend to 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 be unnecessary. 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. Suppose you have a “movies” index where the records have an actors attribute. If this attribute has the full cast, it’s less efficient than if it only had the leading roles. That’s because this is what most users would probably 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 like insertion sorting.

For example, suppose you have the following attributes in the records of a “movies” index:

• director
• cast
• title
• genres
• plot_summary

First, you would compare the first two: director and cast. If you think cast should come before director (for example, you want to see movies with Clint Eastwood before movies directed by Clint Eastwood), you move cast to the first place. Next, you would compare director and title, and likely decide that the name of the movie is more important than the director. That means you’d move title to the second place, and compare it with the previous one (cast). Next, you would 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?

Sometimes it’s better to place filters above all other attributes. This might not seem intuitive at first, as you may think users tend to search by attributes like name or title.

Suppose you have a “movies” index where the records have a genre attribute with values like “crime” and “action.” Films fall into these categories, but there are also films whose titles and descriptions use these same words, for example, “Crime Doesn’t Pay,” “Last Action Hero.”

In that case, you can decide that when a user searches for words that are more like genres, it ‘s best to search filter attributes before the title. This guarantees returning all crime movies whenever someone types in “crime,” regardless of the title.

Making this decision when setting up searchable attributes 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 make decisions based on a single query. Instead, try to experiment with several different queries 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.