Setting up Elasticsearch synonyms for 1C-Bitrix search

Configuring Elasticsearch Synonyms for 1C-Bitrix Search

User searches for "mobile phone" — nothing. Searches "cellular" — also empty. The catalog is full of smartphones, but product names only use "phone". Synonyms in Elasticsearch are a bridge between user vocabulary and actual terms in the index. Without them, full-text search works only for those who guessed the exact word.

Where Synonyms Fit in Elasticsearch Chain

Synonyms are added as a token filter in the analyzer. They can work two ways:

Expansion — "mobile" becomes "mobile phone smartphone". All three tokens go into the query. Results are broader, but relevance spreads thin.

Contraction — "mobile", "cellular", "phone" → all become "phone". In index and in search — one term. Results are precise, but uniformity is needed during indexing.

For Bitrix catalog, contraction on search is preferred: index as-is, collapse synonyms to canonical form on search.

Synonym File and Format

Synonyms can be stored in a file on Elasticsearch server or passed inline in index settings. File approach is more flexible — update dictionary without recreating index.

File /etc/elasticsearch/analysis/synonyms_ru.txt:

# Mobile phones
mobile, cellular, smartphone => phone
iPhone, iphone => phone
Galaxy, galaxy => phone

# Notebooks
notebook, laptop, laptop => notebook
MacBook, macbook => notebook

# Brand synonyms
Samsung, samsung, samsung => samsung
LG, lg => lg

# General terms
TV, telly, tube => television
refrigerator, fridge => refrigerator

# Abbreviations
PC, personal computer => computer
RAM, ram, RAM => memory

File format: term1, term2, term3 => canonical_form for contraction, or term1, term2, term3 for expansion.

Index Configuration with Synonyms

curl -X PUT http://localhost:9200/bitrix_search_s1 \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "analysis": {
      "filter": {
        "russian_stemmer": {
          "type": "stemmer",
          "language": "russian"
        },
        "russian_synonyms": {
          "type": "synonym",
          "synonyms_path": "analysis/synonyms_ru.txt",
          "updateable": true
        }
      },
      "analyzer": {
        "bitrix_search": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "russian_stemmer",
            "russian_synonyms"
          ]
        },
        "bitrix_index": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": [
            "lowercase",
            "russian_stemmer"
          ]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "bitrix_index",
        "search_analyzer": "bitrix_search"
      },
      "body": {
        "type": "text",
        "analyzer": "bitrix_index",
        "search_analyzer": "bitrix_search"
      }
    }
  }
}'

Key: analyzer (for indexing) and search_analyzer (for searching) are different. Synonyms only in search_analyzer — best practice. No extra tokens during indexing, broaden results only on search.

Updating Synonyms Without Reindexing

The updateable: true parameter in synonym filter (Elasticsearch 7.3+) allows updating dictionary without recreating index:

# Edit synonym file
nano /etc/elasticsearch/analysis/synonyms_ru.txt

# Reload analyzers without reindexing
curl -X POST "http://localhost:9200/bitrix_search_s1/_reload_search_analyzers"

This only works for search_analyzer. If synonyms are in index analyzer — full reindexing is needed.

Synonyms via API (Without File)

For small dictionaries — inline synonyms directly in mapping:

"russian_synonyms": {
  "type": "synonym",
  "synonyms": [
    "mobile, cellular => phone",
    "notebook, laptop => notebook",
    "telly, TV => television"
  ]
}

Downside: to update, recreate index and reindex data.

Verifying Synonym Operation

# Check how search_analyzer processes query
curl -X POST "http://localhost:9200/bitrix_search_s1/_analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "analyzer": "bitrix_search",
    "text": "mobile samsung"
  }'

# Expected response: tokens "phone", "samsung"

If synonyms work correctly, query "mobile" will find documents with "phone" token in the index.

Managing Synonyms from Bitrix

Synonym file is convenient to edit via admin interface. Create a simple page in /bitrix/admin/ with form writing to file and calling _reload_search_analyzers API. There are no standard Bitrix tools for this — requires custom development or manual editing via SSH.