Configure a thesaurus
To broaden the search for product information that is performed when a shopper searches on a given term, you can specify one or more thesaurus entries for that term.
The search results include matches on the thesaurus entries as well as on the search term.
To create thesaurus entries, you must first create a thesaurus, which will serve as a container for all your thesaurus entries. You then add an entry to the thesaurus for each thesaurus entry that you want to define.
If your instance of Oracle Commerce is running multiple sites, all sites must share the same thesaurus configuration. You cannot configure the thesaurus differently for the different sites.
This section includes the following topics:
Understand thesaurus entries
You can add two kinds of the following entries to your thesaurus:
- A one-way thesaurus entry, which establishes a mapping between a search term and its thesaurus entry that applies in a single direction only.
For example, you can define a one-way mapping so that all queries on “tools” (the shopper’s search term) return matches containing “hammers” (a synonym for “tools” specified in the thesaurus) as well as matches on “tools”. Note, however, that this mapping works only one way: searching for the thesaurus entry “hammers” does not return matches containing the word “tools”.
- A multi-way thesaurus entry, which specifies two-way mappings among two or more
words or phrases that are treated as equivalents of each other. Note: In the Oracle Commerce interface, the term equivalent is used in place of multi-way.
Use multi-way in the REST API.
For example, a multi-way entry might specify that the terms “adapter”, “converter”, and “adapter converter” are equivalents of each other. A search on any of these terms can return matches on any of the three.
The following table describes the JSON attributes that configure a thesaurus and thesaurus entries.
Attribute | Value |
---|---|
ecr:type |
The ecr-type of the node. The value can be thesaurus or thesaurus-entry . Required.
|
id |
Can be generated by the system or specified by the user. Required for operations on a thesaurus entry. |
thesaurus-entry |
Each entry has the following attributes:
If If |
Example: thesaurus with two thesaurus-entry objects
The following JSON illustrates the configuration of a thesaurus
object containing two thesaurus-entry
objects: a one-way
entry that configures “shirt” as a searchTerms
value and “blouse” as a synonyms
value; and a multi-way
entry that configures “adapter”, “converter”, and “adapter-converter” as synonyms of each other. Note that the ID of one thesaurus-entry
object was generated by the system and the other was specified by the user; for information about how to specify the IDs of thesaurus-entry objects, see Create thesaurus entries.
{
"ecr:type" : "thesaurus",
"auto_generated_id":
{
"ecr:type": "thesaurus-entry",
"type": "one-way",
"searchTerms": "shirt",
"synonyms" : ["blouse"]
},
"user_specified_id":
{
"ecr:type": "thesaurus-entry",
"type": "multi-way",
"synonyms": [
"converter","adapter","adapter-converter"
]
}
}
Thus:
- If a shopper enters “shirt” as a search term, records that include “blouse” appear in the search results; but if a shopper enters “blouse” as a search term, records that include “shirt” do not appear in the search results.
- If a shopper enters any of the words “ adapter”, “converter”, or “ adapter-converter” as a search term, records that contain any of the three words appear in the search results.
Export thesaurus entries
You can use the following endpoint to export thesaurus configuration in JSON or in a ZIP file:
GET /gsadmin/v1/cloud/thesaurus (JSON format)
GET /gsadmin/v1/cloud/thesaurus.zip (ZIP format)
Create thesaurus entries
Execute a POST endpoint with input such as the following to add a thesaurus entry with a user-specified ID to the thesaurus:
POST /gsadmin/v1/cloud/thesaurus/user_specified_id
{
"ecr:type" : "thesaurus-entry",
"type": "one-way",
"synonyms": [
"dig"
]
"searchTerms": "digit"
}
Execute a POST endpoint with input such as the following to add a thesaurus entry with a system-generated ID to the thesaurus:
POST /gsadmin/v1/cloud/thesaurus
{
"ecr:type" : "thesaurus-entry",
"type": "one-way",
"synonyms": [
"dig"
]
"searchTerms": "digit"
}
Execute the following POST endpoint to import thesaurus configuration in a zip file:
POST /gsadmin/v1/cloud/thesaurus
Modify thesaurus entries
Execute a PATCH endpoint to modify the values of existing thesaurus entries. For example, to change the synonym from dig
to digi
for sample_entry_1
, you can execute the PATCH method with the following input:
PATCH /gsadmin/v1/cloud/thesaurus/sample_entry_1
{
"synonyms": ["digi"],
"ecr:type": "thesaurus-entry"
}
Note: PATCH is supported only in JSON format.
Replace the thesaurus
Execute a PUT endpoint to replace the thesaurus in its entirety. For example, the following endpoint replaces configuration of the thesaurus:
PUT /gsadmin/v1/cloud/thesaurus
The new configuration of the thesaurus must be included in the JSON body of the endpoint
.
Note: PUT is supported only in JSON format.