> For the complete documentation index, see [llms.txt](https://docs.abtasty.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abtasty.com/commerce/search/search-configuration.md).
# Search configuration
## Search configuration
**Search** delivers intelligent, catalog-aware search experiences that help visitors find exactly what they need. It runs on the same product catalog as Recommendations and Merchandising, and is configured from the **Search** → **Configuration** page in the Commerce left navigation.
This page covers the four configuration tabs, how visitor-facing suggestions are built, and the query rules that let you fine-tune results.
### Configuration
Open **Search** → **Configuration** from the left navigation. A banner at the top reflects catalog freshness:
{% hint style="info" %}
**Your search catalog is up to date / Last refresh: about 21 hours ago**
{% endhint %}
The search index is rebuilt from your catalog on the same synchronization schedule as the rest of Commerce, see Monitoring Commerce deployment health to track refreshes and synchronizations.
Use **Preview search** (top right) at any time to test queries against your current configuration.
The configuration is split into four tabs:
| Tab | What you configure |
| ----------------------- | ---------------------------------------------------------------------------------- |
| **Relevance** | Which attributes are searched and what minimum quality threshold is applied. |
| **Synonyms** | Equivalent terms, so a query for one word also matches the others |
| **Query understanding** | How much semantic (meaning-based) matching is used, and on which attributes |
| **Advanced parameters** | Displayable attributes, Ranking rules, plus language, region and currency settings |
### Relevance
The **Relevance** tab controls what search returns and how strictly it matches.
**Quality: Result quality threshold**
The **Result quality threshold** filters out irrelevant products. Adjust it to find the right balance between complete results and highly targeted matches that are more likely to convert.
Pick a preset, or set your own value:
| Option | Results shown |
| --------------------------------------- | ----------------------------------------------------------- |
| **Always show results** | All matching results, no minimum score |
| **Show only high-quality matches** | Matching score ≥ `0.85` |
| **Show good-quality matches and above** | Matching score ≥ `0.70` |
| **Show acceptable matches and above** | Matching score ≥ `0.50` |
| **Custom threshold** | Matching score greater than or equal to the value you enter |
Raising the threshold returns fewer, more precise hits; lowering it returns more, broader hits. This corresponds to the `rankingScoreThreshold` parameter exposed in the Search API.
{% hint style="info" %}
Not sure which value to pick? Click **Check ranking scores in the preview** to see the matching score of each product for a real query, then set the threshold just below the last result you want to keep.
{% endhint %}
**Ranking parameters: Searchable attributes for ranking**
The **Ranking parameters** section controls **Searchable attributes for ranking**, *"Define which attributes will be used for text search as well as their level of priority."*
This is an ordered, draggable priority list. Fields higher in the list carry more weight when matching a query. Each row has drag, up/down, and delete controls, and you add fields with **Add other searchable attributes**.
{% hint style="warning" %}
AB Tasty recommends keeping `Title` at the top of the list and only reordering or adding attributes when you have a specific business reason. Avoid technical fields such as image URLs or internal scores. Changes take effect on the next catalog refresh.
{% endhint %}
Any attribute added here is also used by semantic search by default; see Semantic attributes.
### Synonyms
The **Synonyms** tab lets you group related terms so a query for one returns matches for the others (for example, *tshirt* and *tee-shirt*).
**Each rule has a type:**
| Type | Behavior | Example |
| ----------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **One-way** | The keyword expands to its synonyms, not the other way round. | `trainers` → `kicks`: a search for *trainers* also returns *kicks*, but *kicks* does not return *trainers*. |
| **Mutual** | All terms expand to each other. | `sneakers, kicks, trainers`: a search for any of them returns all three. |
**Add a synonym**
1. **Create a new rule.** Click **Add synonym**. A new row appears at the top of the table.
2. **Choose the type.** Click the type badge to switch between **One-way** and **Mutual**.
3. **Enter the terms.** \* **One-way**: enter the keyword (for example *sneakers*), then its synonyms separated by commas (for example *trainers, running shoes*).
* **Mutual**: enter all equivalent terms in a single comma-separated list (for example *sneakers, kicks, trainers*).
4. **Save.** Click the check mark to save the rule, or the cross to cancel.
Use the search field above the table to find a rule, the pencil icon to edit it, and the bin icon to delete it.
**Import synonyms**
To add many rules at once, click **Import synonyms** and paste a JSON object using the following format:
json
```json
{
"word1": ["synonym1", "synonym2"],
"word2": ["synonym3", "synonym4"]
}
```
{% hint style="warning" %}
Imported synonyms are **added** to your existing synonyms. They do not replace them.
{% endhint %}
{% hint style="info" %}
Semantic search already understands many related concepts. Synonyms are most useful for domain-specific vocabulary, brand or product-line names, abbreviations, and regional spellings that semantic search may not infer.
{% endhint %}
### Query understanding
The **Query understanding** tab controls **Semantic search**. It matches products by meaning rather than exact keywords, so a query like *"warm winter jacket"* can surface relevant coats even when those exact words are not in the product fields.
**Semantic search**
Choose how much semantic matching weighs compared with keyword-based relevance:
| Option | Semantic ratio |
| -------------------------------------- | ------------------- |
| **Fully semantic search** | `100%` |
| **Highly semantic search** | `60%` |
| **Balanced semantic search** (default) | `50%` |
| **Lightly semantic search** | `40%` |
| **No semantic search** | `0%` (keyword-only) |
The balance between semantic and keyword matching maps to the `semanticRatio` parameter in the Search API.
{% hint style="info" %}
Higher ratios suit descriptive, natural-language queries. Lower ratios suit catalogs where visitors search with exact references such as SKUs, model numbers or brand names.
{% endhint %}
**Semantic attributes**
**Semantic attributes** lists your searchable attributes, *"Among your search attributes, only the following will be taken into account by the semantic search engine."*
{% hint style="info" %}
Keep descriptive text attributes ticked (for example `title`, `name`, `category`, `description`). Untick technical or numeric fields such as image links, prices or sales scores: they carry no meaning for semantic matching.
{% endhint %}
### Advanced parameters
The **Advanced parameters** tab groups ranking rules and the settings for multi-language, multi-region and multi-currency catalogs.
{% hint style="danger" %}
Advanced parameters are for the admin's account
{% endhint %}
**Display: Displayable attributes**
The **Display** section controls **Displayable attributes**, *"Define which attributes the search API returns for each result."* Each attribute is shown as a removable chip; remove a chip to stop returning that field, or open the dropdown to add one.
The following attributes are always returned and cannot be removed: `img_link`, `link`, `id`, `title`, `price`.
{% hint style="info" %}
Displayable attributes determine which fields are **returned** with each hit (and therefore available to render in the widget or consume via the API). They are independent from which fields are **searched**, that is controlled by the searchable attributes below.
{% endhint %}
**Ranking rules**
**Ranking rules**, *"Define which ranking parameters are most important to you."* Rules are applied in order: when two products tie on a rule, the next rule decides.
| Rule | Effect |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sort** | Results are sorted according to the parameters defined at query time (for example `price:asc`). The higher this rule, the more strictly results follow the requested order, at the expense of relevance. |
| **Exactness** | Returns first the documents whose fields match the query terms exactly. |
| **Attribute** | Returns first the documents in which the query terms appear in the most important searchable attributes. |
| **Words** | Returns first the documents that contain all the query terms. |
| **Typo** | Returns first the documents that match the query terms and contain the fewest typos. |
| **Proximity** | Returns first the documents in which the query terms appear close to each other and in the same order as in the query string. |
Drag a rule, or use its up/down arrows, to change its position.
**Add a custom ranking rule**
Custom ranking rules rank results by a catalog attribute, such as price, stock, margin or popularity.
1. **Open the dialog.** Click **Add a custom ranking rule**.
2. **Select the attribute.** Under **Attributes**, select a product attribute.
3. **Choose the order.** Select **Ascending** (lower values rank higher) or **Descending** (higher values rank higher).
4. **Add the rule.** Click **Add this attribute**. The rule is added at the bottom of the list, for example *price (Ascending): Results with a lower price value will be ranked higher.* Move it up to give it more weight, or use the bin icon to remove it.
{% hint style="warning" %}
Keep custom rules below the default relevance rules unless you deliberately want business criteria to override relevance.
{% endhint %}
**Language: Multilingual search**
**Multilingual search** lets customers search your catalog in multiple languages using translated product content.
| Setting | Description |
| ------------------------------ | ----------------------------------------------------------------------------------------- |
| **Enable multilingual search** | Allows customers to search your catalog in multiple languages. |
| **Search languages** | The languages your customers can use when searching your catalog. |
| **Primary language** | Your catalog's original language. It is used whenever translated content isn't available. |
{% hint style="danger" %}
Changing the **Primary language** changes which language is stored as the original on the next catalog sync.
{% endhint %}
**Region: Multi-region configuration**
**Multi-region configuration** serves different content per region. A region sits above languages and currencies: one region contains its own languages and currencies, so configure regions first.
| Setting | Description |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable multi-region** | Serves region-specific product content. Turn it off for a single-region store. |
| **How regions are defined** | **Countries** or **Custom regions**. |
| **Countries** | Every country you serve different content for. At most 32 regions. |
| **Default region** | The region served when the shopper has not chosen one. Must be one of the selected regions. |
| **Region fields** | The catalog fields that carry region-specific content. Each is stored per language and region (for example `link` → `link_en_it`). Other fields are the same in every region. |
{% hint style="warning" %}
Multi-region requires **Multilingual search**, because a region column always carries a language. If multilingual search is off, turn it back on or switch multi-region off.
{% endhint %}
**Currency: Multi-currency**
**Multi-currency** shows catalog prices in one or more currencies, with a default for each shopper.
| Setting | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Enable multi-currency** | Shows prices in more than one currency. Turn it off for a single-currency store. |
| **Supported currencies** | Every currency your customers can see prices in. |
| **Default currency** | The currency shown when the customer has not chosen one. Must be a supported currency. |
| **Price fields** | The catalog fields that hold prices. Each is stored per currency (for example `price` → `price_eur`). Usually just `price`. |
### Autocomplete and suggestions
Autocomplete gives visitors *"a fast, intuitive search experience by surfacing relevant search suggestions as they type."* It is powered by a dedicated **Suggestions index**
The suggestions index blends two data sources:
| Source | What it contributes |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Past search queries** | Real queries typed by your visitors over roughly the last **8 weeks**. |
| **Catalog-based whitelist** | A verified list of allowed terms extracted from your active product catalog and custom configuration. |
Suggestions are then ranked by:
* **Popularity**: queries typed by a larger number of unique visitors rank higher.
* **Relevance**: broader terms that match more catalog items are preferred.
{% hint style="info" %}
Even a brand-new site with no search history gets catalog-derived suggestions, so high-value products and categories remain suggestible from your very first visitor.
{% endhint %}
### Query rules to optimize results
Query rules let you intervene on specific searches to steer relevance and merchandising. Three mechanisms are available:
* **Redirections**: for specific search terms, send visitors straight to a target page (for example, redirect *"gift card"* to your gift-card landing page). You define the search term and a destination URL.
* **Custom strategies**: query-specific ranking modifications built in the **Strategy Builder**: define the query conditions, then set the filtering and ranking parameters that apply when the query matches.
* **Boost & Bury**: product-level rules that promote (Boost) or demote (Bury) products across searches, at Major / Moderate / Minor strength. These are the same rules used elsewhere in Commerce, see Creating rules: boost and bury.
{% hint style="info" %}
Boost & Bury affects product visibility across all searches; Custom strategies are scoped to the queries they match; Redirections bypass the results page entirely for the matched term.
{% endhint %}
---
# 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.abtasty.com/commerce/search/search-configuration.md?ask=&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.
