'optionalWords' => [ 'word', 'word1 word2', // Both words are optional ... ]
Can be used in these methods:
search, setSettings, browseObjects, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey search, set_settings, browse_objects, search_for_facet_values, generate_secured_api_key, add_api_key, update_api_key search, setSettings, browseObjects, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey search, set_settings, browse_objects, search_for_facet_values, generate_secured_api_key, add_api_key, update_api_key search, setSettings, browse, searchForFacetValues, generateSecuredApiKey, addAPIKey, updateAPIKey search, setSettings, browseObjects, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey Search, SetSettings, Browse, SearchForFacetValues, GenerateSecuredApiKey, AddApiKey, UpdateApiKey Search, setSettings, browse, searchForFacetValues, generateSecuredApiKey, addApiKey, updateApiKey Search, SetSettings, BrowseObjects, SearchForFacetValues, GenerateSecuredAPIKey, AddAPIKey, UpdateAPIKey search, setSettings, browse index, search into facet values, generateSecuredApiKey, add key, update key
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
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.
- 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:
optionalWordscontains less than 10 words, the number of matched words required for a result increments by one.
optionalWordscontains 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).
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
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);