IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« SQL translate API Create or update synonyms set »
Elastic Docs ›Elasticsearch Guide [8.13] ›REST APIs

Synonyms APIs

edit

Synonyms APIs

edit

The synonyms management API provides a convenient way to define and manage synonyms in an internal system index. Related synonyms can be grouped in a "synonyms set". Create as many synonym sets as you need.

This provides an alternative to:

  • Defining inline synonyms in an analyzer definition, which impacts mapping size and can lead to performance issues.
  • Using synonyms files, which implies uploading and managing file consistency on all cluster nodes.

Synonyms sets can be used to configure synonym graph token filters and synonym token filters. These filters are applied as part of the analysis process by the search analyzer.

Synonyms sets are limited to a maximum of 10,000 synonym rules per set. Synonym sets with more than 10,000 synonym rules will provide inconsistent search results. If you need to manage more synonym rules, you can create multiple synonyms sets.

Synonyms sets must exist before they can be added to indices. If an index is created referencing a nonexistent synonyms set, the index will remain in a partially created and inoperable state. The only way to recover from this scenario is to ensure the synonyms set exists then either delete and re-create the index, or close and re-open the index.

Invalid synonym rules can cause errors when applying analyzer changes. For reloadable analyzers, this prevents reloading and applying changes. You must correct errors in the synonym rules and reload the analyzer.

An index with invalid synonym rules cannot be reopened, making it inoperable when:

  • A node containing the index starts
  • The index is opened from a closed state
  • A node restart occurs (which reopens the node assigned shards)

Synonyms sets APIs

edit

You can use these APIs to dynamically update synonyms sets used at search time. Your search results will immediately reflect the synonyms set changes.

Use the following APIs to manage synonyms sets:

Synonym rules APIs

edit

Synonyms sets are composed of synonym rules. Each synonym rule defines a group of words that act as synonyms. You can update individual synonym rules for a specific synonyms set instead of updating the complete synonyms set.

Use the following APIs to manage individual synonym rules in a synonyms set:

« SQL translate API Create or update synonyms set »