Synonym Sets

Subscription

Note

This feature does not work with Solr.
You can add a maximum of 10,000 synonym sets.

A Synonym Set is a group of words or phrases with the same meaning. An administrative User creates the Synonym Set; when a search page end user searches for a keyword or phrase, the synonymous terms in the set are also searched.

For example, a user might search for the word “US”. Most likely, the user would want search results that also included synonyms such as America, U.S.A, United States, etc. By creating Synonym Sets, you can ensure your users get the most out of their searches.

Requirements and Limitations

Synonym Sets are not supported when using Solr as your search engine. Learn about installing Elasticsearch in Getting Started with Elasticsearch.

The => format supported in Elasticsearch is not supported through the Synonyms Set UI.

Creating and Managing Synonym Sets

Create a synonym set by adding as many synonymous keywords to a set as you like. Once the synonym set is saved, searches in the same company scope (any site from the Virtual Instance where the synonyms were configured) take effect.

To create a new synonym set,

From the Global Menu () navigate to Applications → Search Tuning → Synonyms.
Click the Add icon () to add a new Synonym Set.
Enter the list of synonyms in the set. The input of a synonym is accomplished by clicking Enter or by entering a comma.
You can delete synonym by clicking on the X next to it. When you finish your set, click Publish.
To edit or delete a set, click the Options icon () and click on Edit or Delete.

Once your synonym set is published, it is ready to be used.

Using Synonym Sets

You can test your synonym set by searching for one of the synonym keywords you saved in the set. Results matching the keyword and any synonyms are returned in the Search Results widget.

In the example above, this blog article about a lunar rover does not contain the word LRV but is now returned as a search result match. Note that the synonym is also highlighted.

Importantly, each synonym (i.e., word or phrase) in a synonym set is processed like search keywords the user enters into the search bar. For a full-text search in a supported locale, the synonyms undergo analysis by their language filter. The resulting tokens are injected into the search for matching to localized fields. See Synonyms and Localization to learn the out-of-the-box languages supported for synonyms and Creating New Synonym Language Filters for adding new languages.

Synonyms and Localization

Before Liferay DXP 2024.Q4, Synonym Sets worked only with fields indexed into the English or Spanish locales. Beginning in 2024.Q4, synonym graph filters are included out-of-the-box for more languages, including

Language	Locale Code
Portuguese (Brazil)	pt_BR
Portuguese (Portugal)	pt_PT
Italian	it_IT
Arabic (Saudi Arabia)	ar_SA
Catalan (Spain)	ca_ES
Catalan (Andorra)	ca_AD
Catalan (Spain, Valencia)	ca_ES_VALENCIA
Chinese (China)	zh_CN
Chinese (Taiwan)	zh_TW
Dutch (Netherlands)	nl_NL
Dutch (Belgium)	nl_BE
English (US)	en_US
Finnish (Finland)	fi_FI
French (France)	fr_FR
French (Canadian)	fr_CA
German (Germany)	de_DE
Hungarian (Hungary)	hu_HU
Japanese (Japan)	ja_JP
Spanish (Spain)	es_ES
Swedish (Sweden)	sv_SE

To verify the languages supported in your version, you can inspect the index settings for Elasticsearch and OpenSearch.

Important

If you have custom synonym language filters for languages now supported out-of-the-box, remove the custom configuration when you upgrade and execute a full or concurrent reindex.

Creating New Synonym Language Filters

Availability: Liferay DXP 7.3 FP2+ and Liferay DXP 7.2 FP13+

To add support for additional languages, use the configuration steps below:

Create a custom analyzer by re-implementing the default French analyzer with the necessary changes (including an extra Synonym graph token filter in the pipeline)
Add the custom analyzer definition to the index settings, using the Additional Index Configurations of the connector configuration.
Apply the custom analyzer on the desired fields by overriding Liferay DXP’s default type mappings, using the Override Type Mappings setting of the connector configuration.
Reindex to apply the new settings.

Important

If you have custom synonym language filters for any languages supported out-of-the-box in the latest version, remove the custom configuration when you upgrade and execute a full or concurrent reindex.

Prerequisite: Obtain the Default Mappings

You must obtain the Elasticsearch connector’s default JSON mappings before customizing it:

To get the mappings from your running Liferay,

Open the global menu () and go to Control Panel → Search.
Click the Field Mappings tab.
Copy the mappings () and save them.

Warning

Index mappings and settings can change between versions, and sometimes within a minor version (via a Fix Pack or Service Pack). Customizations to the mappings and settings must be reviewed and adapted as necessary when upgrading or moving to a new patch level. In addition, Liferay’s Search team plans to add support for more languages out-of-the-box in future versions, making customizations unnecessary.

Adding a Language

Now that you have the default mapping file, make the necessary changes to add the necessary settings for French language synonyms:

Go to the Elasticsearch connection’s System Settings entry—Elasticsearch 6/7.

Add an analysis block to the Additional Index Configurations field:

{
    "analysis": {
        "analyzer": {
            "custom_liferay_analyzer_fr": {
                "filter": [
                    "french_elision",
                    "lowercase",
                    "french_stop",
                    "my-synonym-filter-fr",
                    "french_stemmer"
                ],
                "tokenizer": "standard"
            }
        },
        "filter": {
            "my-synonym-filter-fr": {
                "lenient": true,
                "synonyms": [],
                "type": "synonym_graph"
            },
            "french_stop":{
                "type":"stop",
                "stopwords":"_french_"
            },
            "french_stemmer":{
                "type":"stemmer",
                "language":"light_french"
            },
            "french_elision": {
                "type": "elision",
                "articles_case": true,
                "articles": [
                    "l", "m", "t", "qu", "n", "s",
                    "j", "d", "c", "jusqu", "quoiqu",
                    "lorsqu", "puisqu"
                ]
            }
        }
    }
}

Adding settings in this configuration augments those available in the out-of-the-box index settings. Find the default JSON settings in the source code’s index-settings.json file. Here you’re creating a new analyzer called custom_liferay_analyzer_fr which uses a new filter my-synonym-filter-fr. The synonyms array is empty for now: Synonym Sets created through the UI will appear here.

Modify the mappings file you copied. Leave the opening curly brace {, but delete lines two and three entirely (the line with the index name and the line with mappings):
```
"liferay-[COMPANY_ID]": {
    "mappings" : {
```
Then, from the end of the mappings, delete the concluding two curly braces.
```
    }
}
```
Note

For Liferay 7.4 U80 or earlier, you must include the LiferayDocumentType declaration at the beginning of the JSON file. For example, see the Liferay 7.4 GA80 mappings

Using the Override Type Mappings field, change the analyzer for the template_fr dynamic field to use the custom analyzer (custom_liferay_analyzer_fr):

Important

This example is clipped for brevity. Override Type Mappings completely overrides and ignores Liferay’s default type mappings, so you must provide a complete mappings file, not just the overridden portion.

 {
  "date_detection": false,
  "dynamic_templates": [
      // (...)
      {
          "template_fr": {
              "mapping": {
                  "search_analyzer": "custom_liferay_analyzer_fr",
                  "store": true,
                  "term_vector": "with_positions_offsets",
                  "type": "text"
              },
              "match": "\\w+_fr\\b|\\w+_fr_[A-Z]{2}\\b",
              "match_mapping_type": "string",
              "match_pattern": "regex"
          }
      },
      // (...)

The important change here is that the default assigned analyzer (french) is replaced with the custom analyzer custom_liferay_analyzer_fr.

Save the changes to the configuration.

Tip

If you’re using the Sidecar Elasticsearch server, you may see an error in the console. Restart Liferay DXP to resolve the issue.
Now go to System Settings → Search → Synonyms.
Add the custom filter name (e.g., my-synonym-filter-fr) to the Filter Names setting and save the configuration.
Perform a full reindex: in Control Panel → Search → Index Actions, click Reindex for All Search Indexes.

To verify that the custom mapping has been applied successfully, go to the Field Mappings tab, choose your index (for example liferay-20101) and look for template_fr in the right panel.

To verify that the additional index settings including your custom analyzer has also been added, make the following API call to Elasticsearch: http://<host>:<port>/liferay-[company-id]/_settings and look for your analyzer name in the response. For example, to see the index settings for the sidecar Elasticsearch server of a Liferay DXP server running at localhost, with a 20101, visit http://localhost:9201/liferay-20101/_settings.

To verify the new filter is working,

Go to the Synonyms application: from the Global menu’s Applications tab, click Synonyms (under Search Tuning).
Create a new Synonym Set: maison, logement.
Create a Web Content Article with English and French translations. Add maison to the French title.
Create another Web Content Article with English and French translations. Add logement to the French title.
Switch to the French locale and search for maison. Both articles are returned.

Capability:

Resource Type:

Official Documentation

Feature:

Search Administration and Tuning

Deployment Approach:

Liferay PaaS

Liferay SaaS

Liferay Self-Hosted