Icon ranking white

Searchable Attributes

Last updated 07 November 2017

Searchable Attributes Overview

Configuring searchable attributes properly is one of the most important ways to achieve great relevance in search results.

By default, when data is pushed to Algolia, the engine makes all of a record’s attributes searchable. However, it’s a good idea to be explicit and tell Algolia which attributes should be searchable. This is because there are many attributes you might want indexed (such as image URLs) that don’t need to be searched. Consider the following record:

{
  "title": "Hamlet",
  "author": "William Shakespeare",
  "content": "...",
  "description": "...",
  "cover_url": "http://bit.ly/x9Djj32",
  "popularity": 520 
}

Users need to search within title, author, content, and description. They don’t need to search for a specific popularity (which may be used internally) or cover_url (which may be used to display images, but the URL itself is unimportant).

It’s important to note that searchable attributes should usually only include text that a user would realistically search for — this would typically exclude numerical attributes like prices, or any other attributes that are only used for display, filtering, or ranking. These sorts of attributes can still be displayed or filtered without making them searchable.

Defining Searchable Attributes

Order By Importance

One of Algolia’s ranking criteria is the order of searchable attributes. Search matches on attributes higher in the list are considered more relevant than matches occuring in attributes further down.

Two or more attributes can also be given the same priority by putting them on the same line, separated by a comma.

Ordered vs. Unordered

An additional setting, Ordered or Unordered, is available on each attribute. If an attribute is specified as Ordered, matching words at the beginning of that attribute will be considered more important than words that occur later in the attribute.

For example, consider the following two objects:

objectA = {
  "title": "iPhone 5"
}

objectB = {
  "title": "Case for iPhone 5"
}

If the title attribute is specified as Ordered, objectA will rank higher than objectB for the query “iPhone” because it matches earlier in the title attribute of objectA.

The same holds true for array attributes — matches early in the array will be considered more relevant than later matches.

If two attributes are equally important, they can be comma-separated on the same line. They will be Unordered.

Restrict Searchable Attributes

At query time, the engine supports granular searches with the restrictSearchableAttributes parameter. Imagine a book search, in which books were structured like this:

books: [
  {
    "title": "Hamlet",
    "author": "William Shakespeare",
    "content": "..."
  },
  {
    "title": "Macbeth",
    "author": "William Shakespeare",
    "content": "..."
  },
  {
    "title": "Shakespeare: The Biography",
    "author": "Peter Ackroyd",
    "content": "..."
  },
  ...
]

The index can be searched in different ways depending on the value of restrictSearchableAttributes — if it’s unused, then searches for “shakespeare” would find matches in any of the attributes title, author or content. However, a content-only search could also be made possible by specifying content in restrictSearchableAttributes. With this configuration, matches of “shakespeare” in the title or author attributes would not be considered.

This parameter is also particularly useful when using deleteByQuery. By ensuring that a destructive query is limited in scope to specific attributes, accidental deletions are less likely.

Nested attributes

Nested attributes are indexed recursively — if a nested attribute is indexed, so are all of its children. Keep this in mind when specifying searchable attributes; if only some of the nested attributes should be searched on, those can be specified more explicitly using dot notation.

Recommendations

Keep attributes short and limit searchable attributes

We recommend against storing attributes with very long values in Algolia — in general, attributes should have fewer than 100 words. Additionally, it’s recommended to have 10 or fewer searchable attributes.

The reasoning here is that the broader the search space, the more likely false positives become. For example, consider a record containing the following text:

Mother died yesterday. I can't be sure.
It could have been yesterday.
The home for the Aged Persons is at Marengo.
It's almost as if Mother weren't really dead. 
The funeral will bring it home to me, 
put an official seal on it, so to speak...

I took the two-o'clock bus. 
It was a blazing hot afternoon.

A query for “yesterday afternoon” will match this record because “yesterday” occurs on the first line and “afternoon” occurs on the last line. However, because the two matches occur so far apart in the record, they should not really be considered relevant. This could be remedied by splitting the record’s text into new objects based on individual paragraphs or sentences.

Aside from relevance concerns, having more searchable attributes also enlarges index sizes, impacting performance.

Always Display Searchable Attributes

When users perform a search, they expect that the displayed results will contain their query. Because of this, we recommend always displaying searchable attributes in user-facing results.

What’s Next

Continue building your Algolia knowledge with these concepts:

© Algolia - Privacy Policy