optionalWords
'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,
GenerateSecuredApiKeys,
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 may appear in a query. Although less important than other query terms, they should still contribute to matching results.
Usually, a record must match all words in the query to be included in the search results. By considering some words as optional, search results will be produced even if only some words in the query match. This is called query relaxation. Records that match all words rank higher than records that match only some words.
Specifying optional words triggers “double querying” where the words are ignored in one query, added in another and the results combined and ranked.
Comparison with removeWordsIfNoResults
Predicting all potential optional words in user-generated queries, such as those typed into a search box, is challenging.
As an alternative, consider using removeWordsIfNoResults
.
Feature | Use when | Limitations | Example |
optionalWords |
You have a known set of words that are less critical for matching | You must maintain a list of optional words | If “cotton” and “casual” are optional words, the query “mens casual cotton shirt” is more likely to return results |
removeWordsIfNoResults |
You want to prioritize returning at least some results. If no results are found, the feature progressively drops words from the query, until there are matches. This means you don’t have to maintain a list of optional words | Can reduce relevance by removing important words. You don’t have much control over what’s removed | The query “laptop 16GB RAM backlit keyboard touchscreen” might be reduced to “laptop” before results appear |
Comparison with stop words
Don’t confuse stop words with optional words or removeWordsIfNoResults
.
- Enabling stop word removal always ignores common words (words that add no value to a search query, such as “the”, “on”, and “it”)
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 a record to be returned increases for every 1,000 records:
- If
optionalWords
contains fewer than 10 words, the number of matching words required for a result increments by one. - If
optionalWords
contains 10 or more words, the required number of matching words increases. This increase is calculated by dividing the number of optional words by 5 (rounded down). For example:- For the first 1,000 results (1-1,000), one matched word is required.
- For results 1,001-2,000, four matched words are needed (the initial 1, plus the calculated increase of 3).
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.
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);