🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
API Reference / API Parameters / optionalWords
Type: string | list of strings
Engine default: []
Parameter syntax
'optionalWords' => [
  'word',
  'word1 word2', // Both words are optional
  ...
]

Can be used in these methods:

About this parameter

A list of words that should be considered optional when found in the query.

When a search doesn’t return enough results, you can increase the number of results by marking some words as optional. This is sometimes called query relaxation.

Usually, a record must match all words in the query to be included in the search results. By adding optional words, records can match only some words in the query. Records that match all words rank higher than records that match only some words.

An alternative to optional words is to use removeWordsIfNoResults.

Don’t confuse stop words with optional words:

  • Enabling stop word removal always ignores common words (words that add no value to a search query, such as “the”, “on”, and “it”)
  • Specifying optional words triggers “double querying” where the specified words are ignored in one query, added in another and the results combined and ranked.

Usage notes

  • You can have more than one list of optional words
  • Each string will be treated as a list of optional words. Don’t put commas between words.
  • The size of the API response will be larger when optional words are added.

There’s no limit to the number of words in the list, but having many words slows down calls to getSettings. This can make the Algolia dashboard slower and less responsive.

What happens with four or more words

If a query has four or more words and all the words are optional, the default behavior of optionalWords changes. The number of matched words needed for an object to be returned increases for every 1,000 objects:

  • If optionalWords contains less than 10 words, the number of matched words required for a result increments by one.
  • If optionalWords contains 10 or more words, the number of matched words required increments by the number of optional words divided by 5 (rounded down). For example, for a query with 18 optional words, the number of matched words needed goes up by three for every 1,000 results returned (1-1,000 require one matched word, 1,001-2,000 results need four matched words).

Examples

Set default list of optional words for all queries

1
2
3
4
5
6
$index->setSettings([
  'optionalWords' => [
    'blue',
    'iphone case'
  ]
]);

Override optional words for the current query

1
2
3
4
5
6
$results = $index->search('query', [
  'optionalWords' => [
    'toyota',
    '2020 2021'
  ]
]);

Doing an OR between all words of a query

By default, Algolia will perform a logical AND between each query word. For example, when searching for iphone case, the engine will return records containing iphone and case. To change this to a logical OR, you must specify each word in the query as an optional word.

1
2
3
4
5
6
7
$query = 'the query';

$params = [
  'optionalWords' => $query
];

$results = $index->search($query, $params);
Did you find this page helpful?