How to Search with Synonyms in Elasticsearch: Simple Guide

To search with synonyms in Elasticsearch, define a synonym filter in your analyzer settings and apply it during indexing or searching. This lets Elasticsearch treat specified words as equivalent, improving search matches for related terms.

Syntax

Elasticsearch uses analyzers with token filters to handle synonyms. You define a synonym filter inside the analysis settings of your index. Then, you apply this filter in a custom analyzer used for indexing or searching.

Key parts:

• filter: Defines the synonym rules.
• analyzer: Uses the synonym filter to process text.
• index or search_analyzer: Specifies when to apply the analyzer.

json

{
  "settings": {
    "analysis": {
      "filter": {
        "synonym_filter": {
          "type": "synonym",
          "synonyms": [
            "quick,fast",
            "jumps,leaps"
          ]
        }
      },
      "analyzer": {
        "synonym_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "synonym_filter"]
        }
      }
    }
  }
}

Example

This example creates an index with a synonym analyzer and searches using it. The synonym filter treats "quick" and "fast" as the same word, so searching for "fast" finds documents with "quick".

json

PUT /my_synonym_index
{
  "settings": {
    "analysis": {
      "filter": {
        "synonym_filter": {
          "type": "synonym",
          "synonyms": [
            "quick,fast",
            "jumps,leaps"
          ]
        }
      },
      "analyzer": {
        "synonym_analyzer": {
          "tokenizer": "standard",
          "filter": ["lowercase", "synonym_filter"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "content": {
        "type": "text",
        "analyzer": "synonym_analyzer"
      }
    }
  }
}

POST /my_synonym_index/_doc
{
  "content": "The quick brown fox jumps over the lazy dog"
}

GET /my_synonym_index/_search
{
  "query": {
    "match": {
      "content": "fast"
    }
  }
}

Output

{
  "hits": {
    "total": {"value": 1, "relation": "eq"},
    "hits": [
      {
        "_source": {
          "content": "The quick brown fox jumps over the lazy dog"
        }
      }
    ]
  }
}

Common Pitfalls

Common mistakes when using synonyms in Elasticsearch include:

• Defining synonyms only at search_analyzer but not at index, causing mismatches.
• Using complex synonym rules without testing, leading to unexpected matches.
• Not reindexing data after changing synonym settings, so changes don't apply.
• Placing synonyms in the wrong filter order, which can affect token processing.

Always test your synonym analyzer with sample queries to ensure expected behavior.

json

/* Wrong: synonym filter only on search_analyzer */
"content": {
  "type": "text",
  "analyzer": "standard",
  "search_analyzer": "synonym_analyzer"
}

/* Right: synonym filter on both index and search analyzers */
"content": {
  "type": "text",
  "analyzer": "synonym_analyzer",
  "search_analyzer": "synonym_analyzer"
}

Quick Reference

• Define synonym filter: List synonyms as comma-separated words.
• Create analyzer: Use tokenizer and synonym filter.
• Apply analyzer: Use in index and search for consistent results.
• Reindex: Required after changing synonyms.

Key Takeaways

Define a synonym filter in your index settings to map related words.

Use a custom analyzer with the synonym filter for indexing and searching.

Apply the synonym analyzer consistently on both index and search to avoid mismatches.

Always reindex your data after updating synonym settings to apply changes.

Test your synonym setup with sample queries to ensure it works as expected.