# Synonyms

{% hint style="warning" %}
**Important:** Synonyms are only supported by the **Index Table search engine**. They have **no effect** when an instance uses the standard (regular) engine. See the [Index Table documentation](https://documentation.ajaxsearchpro.com/index-table) for how to switch an instance to the Index Table engine.
{% endhint %}

You'll find it under **Ajax Search Pro → Synonyms** in the WordPress admin menu.

<figure><img src="/files/HxIfvoabv3R1i0ivevBc" alt=""><figcaption></figcaption></figure>

#### How matching works <a href="#how-matching-works" id="how-matching-works"></a>

* **Expansion is bidirectional.** A synonym group works in every direction — defining *car → automobile, vehicle* means searching for *car*, *automobile* **or** *vehicle* will match content containing any of them. You don't need to create separate entries for each direction.
* **Post/page search bakes synonyms into the index.** For regular content, synonyms are applied when the index is built, so **changing synonyms requires re-creating the index** before the change takes effect (the panel reminds you — see [Re-indexing](http://localhost:63342/markdownPreview/248252425/markdown-preview-index-4t2cp2ji7mitm0kd72lb64c8gn.html#re-indexing)).
* **Taxonomy term search expands at query time.** When searching taxonomy terms (categories, tags, etc.), synonyms are applied live per search, so those don't require a re-index.

***

### Managing synonyms <a href="#managing-synonyms" id="managing-synonyms"></a>

The **Manage** panel lists your synonym entries in a table — the **Term**, its **Synonyms** (a comma-separated list), and the **Language** — with **Edit** and **Delete** actions per row.

The toolbar across the top lets you:

* **Search** — filter the list by term.
* **Language filter** — show entries for *Any language*, *Default*, or a specific language (on multilingual sites).
* **+ Add New** — create a new synonym entry.
* **Export** / **Import** — back up or restore your synonyms (see [Import & export](#import--export)).
* **Wipe All** — delete every synonym (with confirmation).

The list is paginated (10/25/50/100 per page).

<figure><img src="/files/3DVnjRw3M16W1pZlRAep" alt=""><figcaption></figcaption></figure>

#### Adding or editing a synonym <a href="#adding-or-editing-a-synonym" id="adding-or-editing-a-synonym"></a>

Click **+ Add New** (or **Edit** on a row) to open the editor:

* **Term** — the base word or phrase.
* **Synonyms** — the equivalent words. Type each one and press **Enter** or **comma** to add it as a chip.
* **Language** — *Default*, or a specific language on multilingual sites (see [Languages](http://localhost:63342/markdownPreview/248252425/markdown-preview-index-4t2cp2ji7mitm0kd72lb64c8gn.html#languages)).

Click **Save**. Terms and synonyms are normalized automatically (lowercased, trimmed). Because expansion is bidirectional, you only list the alternatives once — no need to repeat the term inside the synonyms.

<figure><img src="/files/HwsYwsfu3QBLovR0W5bs" alt=""><figcaption></figcaption></figure>

***

### Re-indexing <a href="#re-indexing" id="re-indexing"></a>

Whenever you add, edit or delete synonyms, the post index becomes **stale** — the change won't affect post/page results until the index is rebuilt. The panel shows a warning banner when this happens:

> *"Synonyms were changed — the post index may be stale."*

with a link to the **Index Table** page. Run a new index there to apply your synonym changes. (Taxonomy term searches don't need this, since they expand synonyms at query time.)

<figure><img src="/files/O82O0M7ifZ1Ryullt5k2" alt=""><figcaption></figcaption></figure>

***

### Languages <a href="#languages" id="languages"></a>

On multilingual sites (e.g. WPML or Polylang), each synonym entry is tied to a **language**:

* **Default** — applies when no specific language context is set.
* A **specific language** — applies only to searches in that language.

Use the language filter in the toolbar to view and manage entries per language, and set the language in the editor when creating an entry. On single-language sites you can simply leave everything as *Default*.

***

### Import & export <a href="#import--export" id="import--export"></a>

* **Export** downloads all your synonyms as a JSON file (named with a timestamp), ideal for backups or moving synonyms between sites.
* **Import** uploads a synonyms file (JSON) and adds its rows to your list. After importing, the panel tells you how many rows were imported.

***

### AI Synonym Discovery <a href="#ai-synonym-discovery" id="ai-synonym-discovery"></a>

Each row (and the table in the Statistics panels) has a **Discover** button — a sparkle icon — that opens AI-suggested synonyms for that term, grounded in your own content. Click **Add** on a suggestion to apply it instantly. This is part of the [Search AI](https://documentation.ajaxsearchpro.com/search-ai) suite and requires the **AI Synonym Discovery** feature to be enabled there.

<figure><img src="/files/LuXjMiQOd9uG27I860Vr" alt=""><figcaption></figcaption></figure>

***

### Generate synonyms in bulk (AI) <a href="#generate-synonyms-in-bulk-ai" id="generate-synonyms-in-bulk-ai"></a>

Rather than discovering synonyms one term at a time, the **Generate (AI)** button in the toolbar (the sparkle icon) creates synonyms for your **most popular indexed keywords** in one pass, then lets you review and accept them together.

> **Requirements:** the **AI Synonym Discovery** feature must be enabled in [Search AI](https://documentation.ajaxsearchpro.com/search-ai), and your [Index Table](https://documentation.ajaxsearchpro.com/index-table) must be built — the candidate keywords are taken from the index.

It works in two steps:

1. **Configure** — choose how many top keywords to cover (e.g. top 25, 50 or 100) and the **language** for the suggestions, then click **Generate**. Generating for more keywords uses more of your monthly AI token budget.
2. **Review** — the suggestions appear grouped by keyword:
   * Each suggested synonym is a clickable chip; selected ones (highlighted) will be added.
   * Synonyms that are **already in your list** are shown greyed out with an "added" badge and are excluded — nothing is duplicated.
   * Keywords that **already have synonyms are still included**, so the AI can suggest *complementary* additions (marked "complements existing").
   * Click a chip to include or exclude it, then **Add selected** to apply them all at once.

Accepted synonyms are merged into your list (no duplicates), and — as with any synonym change — the post index is marked stale, so run a re-index afterward (see [Re-indexing](#re-indexing)).

<figure><img src="/files/yCpDFLvJJmhAnVHDSjln" alt=""><figcaption></figcaption></figure>

***

### Tips & notes <a href="#tips--notes" id="tips--notes"></a>

* **Switch the instance to the Index Table engine first** — synonyms do nothing on the standard engine.
* **Rebuild the index after changing synonyms** so post/page results reflect the change.
* **One entry, both directions** — you don't need reciprocal entries; expansion is bidirectional.
* **Mine your zero-result searches.** Check the [Statistics](https://documentation.ajaxsearchpro.com/search-statistics) Popular/zero-result phrases and use **Discover** to turn them into synonyms that start matching.
* **Seed a fresh site fast.** Use **Generate (AI)** to create synonyms for your top indexed keywords in one go, then review and accept — a quick head start before fine-tuning by hand.
* **Back up before bulk changes** — Export to JSON before a large import or a Wipe All.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.ajaxsearchpro.com/synonyms.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.