What Are Synonyms in Elasticsearch?
In Elasticsearch, synonyms are used to add semantic equivalences to search queries. For example, if a user searches for "phone," results that include the term "mobile" or "cellular" can also be retrieved.
Types of Synonyms
Bidirectional
Bidirectional synonyms are those where the defined terms are considered equivalent to each other in both directions:
phone, mobile, cellular
If you search for "phone," you will get results that contain "phone," "mobile," or "cellular."
Unidirectional
Unlike bidirectional synonyms, in unidirectional synonyms, a relationship of equivalence is established in only one direction:
iphone, macbook => apple
In this case, searching for "iphone" or "macbook" will return results containing "apple," but a search for "apple" (apple fruit) will not return results with "iphone" or "macbook."
Creating Synonyms in Liferay DXP
Liferay DXP provides the synonym set functionality where you can add different synonyms, although it has the following limitations:
- Only bidirectional synonyms are allowed
- It is limited to 10,000 synonyms
- It does not support all available languages, such as Basque or Galician
At the time of writing this post, the most recent version of Liferay DXP is 2025.Q1 and the Liferay Community version is 7.4 GA132, so these limitations may change in future versions.
Creating Synonyms in Liferay Community
If you are not using the DXP version or do not want to have the limitations mentioned above and you want to maximize the use of synonyms, we can modify an existing Elasticsearch filter in the Liferay configuration called "liferay_filter_synonym_es," which is used by the "liferay_analyzer_es" analyzer, the default analyzer for all Spanish fields within Liferay. Keep in mind that each language has its own filter for synonyms.
To modify the filter, go to Control Panel -> System Settings -> Search - Elasticsearch 7
Next, locate the "Additional Index Configurations" property
If you want to know more about creating your own Elasticsearch filters and analyzers in Liferay, remember that we have specific training on this within the course "Mastering Searches in Liferay"
Adding Synonyms Directly to the Filter
Within the property located in the previous step, enter the following:
{
"analysis": {
"filter": {
"liferay_filter_synonym_es": {
"lenient": true,
"synonyms": [
"phone, mobile, cellular",
"iphone, macbook => apple"
],
"type": "synonym_graph"
}
}
}
}Adding Synonyms to Elasticsearch
The previous option is perfectly valid, but when we have to work with many synonyms, it can be quite difficult to manage.
Therefore, the other option is to add a file with all the synonyms to Elasticsearch (you can add up to 10,000 synonyms in a file, and you can have multiple synonym files. You can consult the information about synonyms directly in Elasticsearch to see how to proceed in these cases) and then reference it in the previous Liferay configuration.
Adding a Synonym File to Elasticsearch
The file must be created within the configs directory of your Elasticsearch installation. For example, if you are using the official Docker image docker.elastic.co/elasticsearch/elasticsearch:7.17.15, you should create it inside /usr/share/elasticsearch/config/synonyms/synonyms_es.txt. Note that we have also created a directory called "synonyms" simply for organization purposes
The content of this file includes the different synonyms you want to create, each on a different line. Following the previous example, it would look like this:
phone, mobile, cellular
iphone, macbook => appleModifying the Liferay Configuration
Within the "Additional Index Configurations" property located earlier:
{
"analysis": {
"filter": {
"liferay_filter_synonym_es": {
"lenient": true,
"synonyms_path": "synonyms/synonyms_es.txt",
"type": "synonym_graph"
}
}
}
}Reindexing the Information
Finally, once the synonyms are configured, we need to reindex the information in Elasticsearch. To do this, go to Control Panel -> Search -> Index Actions -> All Search Indexes (Reindex)
Testing the Result
Keep in mind that synonyms are always dependent on the search context, so each search system must establish its own synonym equivalence rules. Using them correctly can make a big difference in search quality and significantly improve the user experience.
