Elasticsearch Synonyms and Stop Words

People describe one thing in many ways. One shopper types "sofa," another types "couch," and a third types "settee." A search engine that matches only exact words would miss two out of three. Synonyms close that gap. Stop words solve a different problem by removing filler words that add noise to the index.

How Synonyms Work

A synonym filter sits inside an analyzer. It expands or replaces tokens using a list of word groups that you provide.

Synonym group:  sofa, couch, settee

Visitor searches:  "couch"
                      │
          synonym filter expands the query
                      ▼
          sofa OR couch OR settee
                      │
                      ▼
   Finds documents containing any of the three words

Equivalent Synonyms

A comma-separated list tells Elasticsearch that all the words mean the same. Any word in the group matches every other word.

laptop, notebook, portable computer
sofa, couch, settee

One-Way Synonyms

An arrow creates a directed rule. Words on the left turn into the words on the right. Use it when a short form should map to a full form, without the reverse.

tv, telly => television
u.s.a, usa => united states

A search for "tv" now finds "television." A search for "television" does not need to find "tv."

Setting Up an Inline Synonym Filter

The simplest approach places the rules directly in the index settings. The synonym_graph filter handles multi-word synonyms correctly, so it works better than the older synonym filter for search-time use.

PUT /furniture
{
  "settings": {
    "analysis": {
      "filter": {
        "my_synonyms": {
          "type": "synonym_graph",
          "synonyms": [
            "sofa, couch, settee",
            "tv, telly => television"
          ]
        }
      },
      "analyzer": {
        "synonym_search": {
          "tokenizer": "standard",
          "filter": ["lowercase", "my_synonyms"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "standard",
        "search_analyzer": "synonym_search"
      }
    }
  }
}

Why Apply Synonyms at Search Time

Synonyms applied during indexing bake the expanded words into stored data. A change to the list demands a full reindex. Synonyms applied at search time touch only the query, so the list can change without rebuilding anything.

Approach	List Changes	Index Size
Index time	Requires reindexing	Larger
Search time	Reload only	Unchanged

Managing Synonyms with the Synonyms API

Version 8.10 introduced synonym sets, which live inside the cluster and update through an API. Define a set once, and any index can reference it.

PUT /_synonyms/furniture-synonyms
{
  "synonyms_set": [
    { "id": "seat-1", "synonyms": "sofa, couch, settee" },
    { "id": "tv-1",   "synonyms": "tv, telly => television" }
  ]
}

"my_synonyms": {
  "type": "synonym_graph",
  "synonyms_set": "furniture-synonyms",
  "updateable": true
}

Editing the set updates the search analyzers that use it, with no index closing and no downtime. A filter marked updateable works only inside search-time analyzers.

Testing Synonym Behavior

GET /furniture/_analyze
{
  "analyzer": "synonym_search",
  "text": "couch"
}

Tokens: couch, sofa, settee

Stop Words

Stop words are very common words, such as "the," "is," and "and." They carry little meaning for ranking and fill the index with entries. The stop filter removes them.

Text:          "The history of the Roman Empire"

standard:      [the] [history] [of] [the] [roman] [empire]
with stop:     [history] [roman] [empire]

Configuring the Stop Filter

"filter": {
  "english_stop": {
    "type": "stop",
    "stopwords": "_english_"
  },
  "my_stop": {
    "type": "stop",
    "stopwords": ["demo", "sample", "test"]
  }
}

The _english_ keyword loads a built-in list. A custom array handles words specific to your business, such as filler terms that appear in every product title.

Risks of Removing Words

Aggressive stop word lists damage some searches. The phrase "to be or not to be" consists entirely of common words, and a stop filter would reduce it to nothing. Band names, movie titles, and short questions often depend on small words.

Situation	Recommendation
Long articles and reports	Stop words help reduce noise
Titles, names, short phrases	Keep stop words
Phrase search needed	Keep stop words

Modern Elasticsearch scoring already lowers the weight of very common words, so many projects skip stop words and let relevance scoring handle the job.

Maintaining the Synonym List

A synonym list grows with the business. Review search logs regularly and look for queries that return no results. Each empty result often hides a missing synonym, such as a new product nickname or a regional spelling.

Keep the list small and meaningful. Linking words that only sometimes mean the same thing, such as "bank" for a river edge and a money institution, produces confusing matches. Group only words that share meaning in your own data, and test each change with the analyze API before release.