21 Nov 2018

Optional Words

Default Query Behavior

By default, Algolia returns matches that contain all of a query’s words:

"big hamster wheel" ➡️ "big" AND "hamster" AND "wheel"

This is the behavior users have come to expect from search experiences on major sites like Google, Facebook and Amazon.

Introduction to Optional Words

optionalWords are helpful in expanding a result set in several contexts:

  • when users are commonly searching with queries that are more specific than the actual records
  • when users are consistently getting no results for queries that should return results
  • when users’ multi-word queries tend to describe multiple distinct objects versus a unified concept — consider tables chairs cutlery versus round outdoor table

Setting Optional Word Defaults

You don’t need to put commas between words. Each string will automatically be tokenized into words, all of which will be considered as optional:

  optionalWords: [
    'word2 word3 word4'

These settings can be applied at index time or query time.

Treating All Query Words as Optional

Treating all of a query’s words as optional transforms every implicit AND to an OR. This can be useful as a way to generate “related results”, or to avoid empty result sets.

This can be done by setting the query itself to the value of optionalWords:

"big hamster wheel" ➡️ "big" OR "hamster" OR "wheel"

var query = "big hamster wheel";

// Sets "big", "hamster", and "wheel" as optional
var params = {
  'optionalWords': query


The removeWordsIfNoResults API parameter can accept a value of allOptional, which would treat all of a query’s words as optional only if there are no results from the original query.

© Algolia - Privacy Policy