> For the complete documentation index, see [llms.txt](https://docs.codegiganten.de/plugin-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/synonyms.md).

# Synonyms

Maintain synonyms so the search finds the right products even when customers use a different word for the same thing.

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-915ba8af6f029beaaac34d367caa7872c31b9e24%2Fsuche-intelligent-und-ki-optimiert-synonyme.png?alt=media" alt="Synonyms area with a note, the number of synonyms per data source and the product feed selection"><figcaption></figcaption></figure>

Customers do not always use the word that appears in your product texts. Some search for "pullover", others for "sweatshirt" or "hoodie". With synonyms you tell the search that these words mean the same thing. When a customer searches for one of them, the search also considers products described with the other words.

You maintain synonyms in the plugin dashboard under **Synonyms**. At the top, choose the data source whose synonyms you want to edit under "Select product feed". The overview "Configured synonyms per data source" shows how many synonyms exist for each source.

## What synonyms are for

* Different words for the same product: "sofa" and "couch", "mobile" and "smartphone".
* Technical term and everyday word: "cordless screwdriver" and "power driver".
* Spelling variants and abbreviations used in your range.
* Terms customers search for but that you name differently, for example "trousers" for products you call "pants".

Synonyms do not replace clean product data. They are the fastest fix when you see that customers find nothing with a certain word.

## Create a synonym

1. Choose the data source under "Select product feed".
2. Type the new synonym in the empty field at the end of the list.
3. Click "Add".

The field then clears and the list reloads. Each entry has the buttons "Edit" and "Delete". Editing opens a small input window with the current text. Before deleting, the browser asks for confirmation.

## Notation

There are two ways to write a synonym.

| Notation                        | Example                        | Effect                                                                                                                              |
| ------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Equivalent, separated by commas | `Pullover, Sweatshirt, Hoodie` | All terms count as synonyms of each other, in both directions. At least two terms.                                                  |
| One-way with `=>`               | `Trousers, Jeans => Pants`     | Whoever searches "trousers" or "jeans" also gets results for "pants". Whoever searches "pants" does not automatically get trousers. |

Spaces around commas do not matter, empty parts are ignored. An equivalent synonym with fewer than two terms cannot be saved. You then see a general error message about saving.

{% hint style="info" %}
Use the equivalent notation when the words are truly interchangeable. Use `=>` when only one direction is correct. A "pullover" is a "top", but not every top is a pullover.
{% endhint %}

### Multi-word terms

A term may consist of several words, for example `deco candle holder, candle holder`. The search then recognizes the whole word sequence in the customer's input.

## How synonyms work in the search

When a customer enters a search term, the search checks whether it contains a term from your synonyms. If so, it builds additional variants of the search in which that term is replaced by the alternatives. The original and the variants are searched together, so a product only needs to match one of them.

The following applies:

* **Variants count less.** With otherwise equal quality, hits for the word the customer typed rank above hits found only through a synonym.
* **At most five variants** are built in addition to the original search.
* **Whole words.** The synonym "trousers" applies to "trousers blue", but not in the middle of a longer word.
* **Upper and lower case do not matter.** "trousers", "Trousers" and "TROUSERS" are the same.
* **Umlauts are treated alike.** "ä" and "ae", "ö" and "oe", "ü" and "ue", "ß" and "ss" count as the same.
* **The longest term wins.** If two synonyms overlap in the input, for example "deco candle holder" and "candle holder", the longer term is used.

## Examples

**Pullover, Sweatshirt, Hoodie.** A customer searches "hoodie black". The search also looks for "pullover black" and "sweatshirt black". Products that only have "sweatshirt" in the title now appear too, slightly below real "hoodie" hits.

**Trousers, Jeans => Pants.** Your range calls trousers "pants". Customers who type "jeans" or "trousers" still see these products. Whoever types "pants" gets no additional trousers, because the rule only works in one direction.

**Couch, Sofa.** Created as equivalent, each term finds the products of the other.

## Create synonyms from "Lost opportunities"

In the search term rules, the "Lost opportunities" list shows terms where customers find nothing. Each term has the action "Create synonym". A window opens in which you enter further terms separated by commas, for example "couch, sofa". If the search already corrected the term itself, the correction is pre-filled. Afterwards the search treats the words as equivalent, in both directions.

More on the page [Search term rules](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-term-rules.md). In [Statistics](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/statistics.md), a link next to the search terms without results also leads to synonym maintenance.

## AI synonym suggestions (beta)

In the AI area, InsightSearch suggests synonyms that you accept with one click. The suggestions come from your product data and from your customers' search behavior. Accepted suggestions are saved as equivalent groups in your synonyms. Details are on the page [AI features](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/ai-features.md).

## When changes take effect

New and changed synonyms take effect in the search after a short time, because the search briefly stores results in a cache. Expect a few seconds up to a few minutes. A synonym created from "Lost opportunities" usually works after a few seconds, an accepted AI suggestion after a few minutes.

A **deleted** synonym can keep working until the product data is read in again the next time. If it should disappear right away, re-read the product data under **Sources** with "Re-read product data".

## Synonyms and the automatic filter

The search can recognize words in the input as filters, for example a brand or a category. Synonyms influence this: if a synonym declares a word in the input as dispensable, the search no longer turns it into a hard filter. The word then only serves as a hint for the order. An example is the synonym `deco candle holder => candle holder`. The word "deco" then no longer filters to a category "Deco". A true synonym such as "mobile" and "smartphone" makes no word dispensable. You do not need to set anything for this.

## Tips

* Start with the terms from "Lost opportunities" and the searches without results in the statistics. There you see what customers really type.
* Create a few precise synonyms rather than long chains. The more words in a group, the more likely unrelated hits appear.
* Check the effect in the shop with the search term itself, for example in the "Search sandbox".
* Typos do not need a synonym. The search compensates small typos on its own.
* Maintain synonyms per data source. Each source has its own list.

## Read more

{% content-ref url="/pages/YEBvytB69E4Y4qAMmqvE" %}
[Filters](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/filters.md)
{% endcontent-ref %}

{% content-ref url="/pages/DH2IbZLins4ioA38ZbKv" %}
[Search term rules](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-term-rules.md)
{% endcontent-ref %}

{% content-ref url="/pages/vYvr8CZPfJEADtRAIFKl" %}
[AI features](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/ai-features.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/synonyms.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
