Synonym handling in Elasticsearch - Step-by-Step Execution

Concept Flow - Synonym handling

User Query Input

↓

Analyze Query Text

↓

Apply Synonym Filter

↓

Expand Query with Synonyms

↓

Search Expanded Query in Index

↓

Return Matching Documents

The query text is analyzed and synonyms are applied to expand the search terms, improving search results by including related words.

Execution Sample

Elasticsearch

PUT /my_index
{
  "settings": {
    "analysis": {
      "filter": {
        "my_synonym_filter": {
          "type": "synonym",
          "synonyms": ["quick,fast"]
        }
      },
      "analyzer": {
        "my_synonym_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "my_synonym_filter"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "content": {
        "type": "text",
        "analyzer": "my_synonym_analyzer"
      }
    }
  }
}

GET /my_index/_search
{
  "query": {
    "match": {
      "content": "fast car"
    }
  }
}

Defines an index with a synonym filter that treats 'quick' and 'fast' as the same, then searches for 'fast car' which also matches documents with 'quick car'.

Execution Table

Step	Input Text	Analyzer Action	Tokens After Analysis	Query Expansion
1	fast car	Tokenize and lowercase	["fast", "car"]	Apply synonym filter
2	fast	Synonym filter expands	["fast", "quick"]	Expand query to include 'quick'
3	car	No synonym	["car"]	No expansion
4	Final tokens	Combine tokens	["fast", "quick", "car"]	Search with expanded terms
5	Search	Match documents with any token	Documents with 'fast car' or 'quick car'	Return results

💡 All tokens processed and query expanded with synonyms for search

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
tokens	[]	["fast", "car"]	["fast", "quick", "car"]	["fast", "quick", "car"]	["fast", "quick", "car"]
query_terms	[]	["fast", "car"]	["fast", "quick", "car"]	["fast", "quick", "car"]	["fast", "quick", "car"]

Key Moments - 3 Insights

Why does the token 'fast' become two tokens 'fast' and 'quick' after synonym filter?

Because the synonym filter expands 'fast' to include its synonym 'quick', so the query searches for both words to find more matches (see execution_table step 2).

Does the synonym filter change the original tokens or add new ones?

It adds new tokens alongside the original ones, so both 'fast' and 'quick' are searched, not replacing 'fast' (see execution_table step 2 and 4).

Why is the analyzer applied at both index and search time?

To ensure that synonyms are recognized consistently when indexing documents and when searching, so queries match documents correctly.

Visual Quiz - 3 Questions

Look at the execution_table at step 2, what tokens are present after applying the synonym filter to 'fast'?

A ["fast"]

B ["fast", "quick"]

C ["quick"]

D ["fast", "car"]

💡 Hint

Check the 'Tokens After Analysis' column at step 2 in the execution_table.

At which step does the query get expanded to include synonyms?

A Step 2

B Step 1

C Step 3

D Step 5

💡 Hint

Look for when the synonym filter is applied and tokens increase in the execution_table.

If the synonym filter was removed, how would the tokens after step 2 change?

A ["fast", "quick", "car"]

B ["quick", "car"]

C ["fast", "car"]

D ["car"]

💡 Hint

Without synonym filter, tokens remain as originally tokenized (see variable_tracker start and after step 1).

Concept Snapshot

Synonym handling in Elasticsearch:
- Define a synonym filter in analysis settings
- Use it in a custom analyzer
- Analyzer expands tokens with synonyms at index and search time
- Queries match documents with original or synonym terms
- Improves search recall by including related words

Full Transcript

Synonym handling in Elasticsearch means when you search for a word, the system also looks for its synonyms to find more results. The process starts when the user inputs a query. The query text is analyzed by breaking it into tokens and converting to lowercase. Then the synonym filter is applied, which expands tokens like 'fast' to include 'quick'. This expansion means the search will look for documents containing either word. The final expanded tokens are used to search the index, returning documents that match any of the tokens. This helps find more relevant documents even if they use different words with the same meaning. The synonym filter adds new tokens alongside original ones, not replacing them. It is important to apply the same analyzer at index and search time to keep consistency. This way, synonyms improve search results by broadening the matching terms.