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.

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: `Type`: (string, required). The supported values are: `one-way`: Specifies a single thesaurus entry for the `searchTerms` value. If entered as a search term, a `searchTerms` value matches the synonyms value; but a synonyms value, if entered as a search term, does not match a `searchTerms` value. `equivalent`: Specifies a list of synonyms, any one of which, if entered as a search term, matches any of the other synonyms. Note: In the REST API, the term `multi-way` is used in place of `equivalent`. `searchTerms`: (string) Required if the `Type` value is `one-way`. Not used if the entry type is `multi-way`. `synonyms`: (string or string[], required). The `synonyms` values are treated in the following ways: If `type` is `one-way`, the `synonyms` value is a single word or phrase that is considered a match for the `searchTerm` value. If `type` is `multi-way`, the `synonyms` value is a set of two or more words or phrases, any one of which is considered a match for any of the others when entered by the user as a search term.

thesaurus-entry

Each entry has the following attributes:

Type: (string, required). The supported values are:

one-way: Specifies a single thesaurus entry for the searchTerms value. If entered as a search term, a searchTerms value matches the synonyms value; but a synonyms value, if entered as a search term, does not match a searchTerms value.

equivalent: Specifies a list of synonyms, any one of which, if entered as a search term, matches any of the other synonyms. Note: In the REST API, the term multi-way is used in place of equivalent.

searchTerms: (string) Required if the Type value is one-way. Not used if the entry type is multi-way.

synonyms: (string or string[], required). The synonyms values are treated in the following ways:

If type is one-way, the synonyms value is a single word or phrase that is considered a match for the searchTerm value.

If type is multi-way, the synonyms value is a set of two or more words or phrases, any one of which is considered a match for any of the others when entered by the user as a search term.

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.