Skip to main content
The optionalWords parameter defines which words in the query are considered optional. By default, all query terms must match for a record to be included in the search results. For example, a search for phone case only returns records where the words phone and case occur in the searchable attributes. Optional words allow for query relaxation. For example, with phone and case as optional words, the same search returns records with the words phone or case. Matches with all words rank higher than matches with only non-optional words.
When using optional words, Algolia performs “double querying”: one query with all terms, and another where optional words are removed. Results are merged and re-ranked.

​
Usage

  • You can include multiple optional phrases or word sets.
  • Each string is interpreted as a set of optional words. Don’t separate words with commas.
  • This feature increases the response size.
  • There isn’t a hard limit on the number of words, but using too many can slow down getSettings and the Algolia dashboard.

​
Long queries

If the query contains four or more optional words, the required number of matched words in a record increases for every 1,000 records:
  • If optionalWords has up to 10 words, the required number of matched words increases by 1.
  • If optionalWords has 10 or more words, the required number of matching words is based on the number of optional words divided by 5 (rounded down). For example:
    • For the first 1,000 results, 1 matched word is required.
    • For the next 1,000 results, 4 matched words are needed (the initial 1, plus the calculated increase of 3).

​
Comparison with removeWordsIfNoResults

Use removeWordsIfNoResults when you want optional behavior only if no results are found. This is more adaptive for unpredictable, user-generated queries.

​
Comparison with stop words

Stop word removal always ignores common words (words that add no value to a search query, such as “the”, “on”, and “it”)

​
Examples

Current API clients

​
Set default list of optional words for all queries

This example sets "blue" and "iphone case" as optional words for all queries. That means, a query for blue iphone case matches records that match either blue, or iphone case, or both.
IndexSettings settings = new IndexSettings();
settings.OptionalWords = new List
{
  "blue",
  "iphone case"
},

index.SetSettings(settings);

​
Override optional words for the current query

index.Search(new Query("")
{
    OptionalWords = new List
    {
      "toyota",
      "2020 2021"
    },
});

​
Set default list of optional words for all queries

This example sets "blue" and "iphone case" as optional words for all queries. That means, a query for blue iphone case matches records that match either blue, or iphone case, or both.
IndexSettings settings = new IndexSettings();
settings.OptionalWords = new List
{
  "blue",
  "iphone case"
},

index.SetSettings(settings);

​
Override optional words for the current query

index.Search(new Query("")
{
    OptionalWords = new List
    {
      "toyota",
      "2020 2021"
    },
});
⌘I