Synonym handling in Elasticsearch

Introduction

Synonym handling helps search engines find results even if words are different but mean the same thing.

When users search with different words but expect the same results.

To improve search accuracy by including related terms automatically.

When you want to group similar words like 'car' and 'automobile' together.

To handle spelling variations or abbreviations in search queries.

When you want to expand search results without changing the original data.

Syntax

Elasticsearch

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

The synonym filter lists words that mean the same.

The analyzer uses this filter to treat synonyms as equal during search.

Examples

This example groups 'happy', 'joyful', and 'glad' as synonyms for searching in a books index.

Elasticsearch

PUT /books
{
  "settings": {
    "analysis": {
      "filter": {
        "synonym_filter": {
          "type": "synonym",
          "synonyms": ["happy, joyful, glad"]
        }
      },
      "analyzer": {
        "synonym_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "synonym_filter"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "analyzer": "synonym_analyzer"
      }
    }
  }
}

This example loads synonyms from a file called synonyms.txt for a products index.

Elasticsearch

PUT /products
{
  "settings": {
    "analysis": {
      "filter": {
        "synonym_filter": {
          "type": "synonym",
          "synonyms_path": "analysis/synonyms.txt"
        }
      },
      "analyzer": {
        "synonym_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "synonym_filter"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "synonym_analyzer"
      }
    }
  }
}

Sample Program

This program creates an index where 'car', 'automobile', and 'auto' are synonyms. It adds a document with 'automobile' and searches using 'car'. The search will find the document because of synonym handling.

Elasticsearch

PUT /vehicles
{
  "settings": {
    "analysis": {
      "filter": {
        "vehicle_synonyms": {
          "type": "synonym",
          "synonyms": [
            "car, automobile, auto",
            "bike, bicycle"
          ]
        }
      },
      "analyzer": {
        "vehicle_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "vehicle_synonyms"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "analyzer": "vehicle_analyzer"
      }
    }
  }
}

POST /vehicles/_doc/1
{
  "description": "I love my automobile"
}

GET /vehicles/_search
{
  "query": {
    "match": {
      "description": "car"
    }
  }
}

Important Notes

Synonyms improve search but can make indexing slower.

Keep synonym lists simple to avoid confusing results.

Synonym filters work best when applied at index time or search time, but not both.

Summary

Synonym handling helps find results with different words that mean the same.

Define synonyms in filters and use them in analyzers.

Use synonyms to improve search experience without changing data.