Synonym Sets
Subscription
- This feature works only with Elasticsearch.
- 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 only supported when using Elasticsearch as your search engine. Learn about installing Elasticsearch in Getting Started with Elasticsearch.
Synonym Sets currently work with fields indexed in either of the following out-of-the-box locales: English or Spanish. Liferay assets with localizable fields in either of these two languages work with Synonym Sets.
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.
Creating New Synonym Language Filters
Availability: Liferay DXP 7.3 FP2+ and Liferay DXP 7.2 FP13+
Out of the box, Synonyms Sets supports synonyms in English and Spanish only. To add support for other 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.
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.
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 verisons, 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 calledcustom_liferay_analyzer_fr
which uses a new filtermy-synonym-filter-fr
. Thesynonyms
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 withmappings
):"liferay-[COMPANY_ID]": { "mappings" : {
Then, from the end of the mappings, delete the concluding two curly braces.
} }
NoteFor 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
):ImportantThis 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": { "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 analyzercustom_liferay_analyzer_fr
. -
Save the changes to the configuration.
TipIf 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.,
custom-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 fortemplate_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 atlocalhost
, with a20101
, 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.