Synonym Sets
Subscribers
This feature works only with Elasticsearch.
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.
- Re-index 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 Liferay DXP bundle,
- Go to
[Liferay Home]/osgi/marketplace
. - Find the LPKG
Liferay Foundation - Liferay Connector to Elasticsearch 6/7 - Impl.lpkg
. - Open with an archive manager, then extract the JAR file that has the name pattern
com.liferay.portal.search.elasticsearch6/7-x.y.z.jar
. - Open the extracted JAR file with an archive manager and go to
META-INF/mappings
. - The file called
liferay-type-mappings.json
is the resource you need. Extract it to your file system.
To get the mappings from the source code, if you have Liferay DXP Source Code Access,
- Once you have access to the source code repository, follow the steps from the article above to find the tag for your fix pack level.
- Navigate to
modules/apps/portal-search-elasticsearch(6 or 7)/portal-search-elasticsearch(6 or 7)-impl/src/main/resources/META-INF/mappings
- Here you will find the mentioned JSON file (
liferay-type-mappings.json
).
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.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.
{ "LiferayDocumentType": { "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 re-index: in Control Panel → Search → Index Actions, click Reindex 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.