Synonyms

Overview

Synonym functionality allows e-shop administrators to enable their users to use search terms that are not present in their product feed.

For example, users can enter search phrases that contain professional or culture-specific jargon, and still discover the products that they are looking for.

Synonyms can be added in a context of a search index. LupaSearch allows adding two types of synonyms: equivalent and directional.

Equivalent synonyms

Equivalent synonym entry describes words or phrases that more or less mean the same thing in the context of your e-shop. For example, if equivalent synonym entry

small, little, miniature, narrow, short

is added as a synonym, user query small fridge would match products with names like:

• small fridge;
• fridge - short;
• narrow, compact fridge.

The same results would still be present for similar user queries, like little fridge or miniature fridge. However, exact matches (like small fridge in the example above) will always be displayed at the top of the search results, unless these rules are overridden with your custom query boosting.

Directional synonyms

Directional synonyms are applied only one way, and are best used to override jargon or other words and phrases that are not directly present in the fields of your product feed.

For example, directional synonym entry:

monochrome => black and white, greyscale, grayscale

with user query monochrome picture would match entries like:

• black and white picture;
• picture - greyscale.

However, query black and white picture would not match any of the following phrases:

• monochrome picture;
• picture - greyscale.

Adding synonyms

LupaSearch allows adding synonyms using the API or directly through the dashboard.

Using synonym API

You can use synonyms API to manage your synonym entries for the selected search index.

Issue a POST request with synonym entries in the body.

POST /v1/indices/{indexId}/

[
  {
    "synonymEntry": "dog, puppy, hound, canine"
  },
  {
    "synonymEntry": "monochrome => black and white, greyscale, grayscale"
  },
  {
    "synonymEntry": "small, little, miniature, narrow, short"
  }
]

You can add multiple synonym entries and once.

Response will include ids and additional data about the created synonyms:

[
  {
    "id": "9bb729d0-2a53-4314-9279-5336d8d2edae",
    "synonymEntry": "dog, puppy, hound, canine",
    "createdAt": "2022-06-17T08:10:14.000Z"
  },
  {
    "id": "9d25762d-9b1e-47cf-92cb-a356947166cd",
    "synonymEntry": "small, little, miniature, narrow, short",
    "createdAt": "2022-06-17T08:10:14.000Z"
  },
  {
    "id": "f636ad49-80d1-4c8c-8744-5e2fde352341",
    "synonymEntry": "monochrome => black and white, greyscale, grayscale",
    "createdAt": "2022-06-17T08:10:14.000Z"
  }
]

Full examples: Api Docs

Using dashboard

You can also manage synonyms directly in the Synonyms Dashboard. Dashboard allows listing, filtering, deleting and adding new synonym entries.

The interface also provides ability to import documents from a text file.

File should contain one synonym entry on each line, for example:

dog, puppy, hound, canine
small, little, miniature, narrow, short
monochrome => black and white, greyscale, grayscale

Retrieve synonyms

You can retrieve synonyms using GET API:

GET /v1/indices/{indexId}/synonyms

Example of a response:

[
  {
    "id": "87951801-813d-47d3-a834-55ac339bd247",
    "synonymEntry": "dog, puppy, hound, canine",
    "createdAt": "2022-06-17T08:09:58.000Z"
  },
  {
    "id": "9d25762d-9b1e-47cf-92cb-a356947166cd",
    "synonymEntry": "small, little, miniature, narrow, short",
    "createdAt": "2022-06-17T08:10:14.000Z"
  },
  {
    "id": "f636ad49-80d1-4c8c-8744-5e2fde352341",
    "synonymEntry": "monochrome => black and white, greyscale, grayscale",
    "createdAt": "2022-06-17T08:10:14.000Z"
  }
]

Full example: Api Docs

Deleting synonyms

To delete synonyms use POST request:

POST /v1/indices/{indexId}/synonyms/batchDelete

With a list of synonym ids that you want to delete:

{
  "ids": [
    "87951801-813d-47d3-a834-55ac339bd247",
    "b3de6888-b340-43f2-a158-5b9684c4fc9c"
  ]
}

Full example: Api Docs

Synonyms in autocomplete suggestions

Synonyms that are created in the document index, are automatically applied to all child suggestion indices. This means that when e-shop user is using autocomplete search box, he will get synonyms as possible suggestion phrases, if there are no other regular entries that begin with those initial letters.

For example, with synonym entry monochrome => black and white, greyscale, grayscale, and user query: monoc, suggestion box may look like this (if there are no other entries in the suggestion index that start with monoc):

• black and white;
• greyscale;
• black white;