> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration of the search module
> Align the WEBSALE | search import module and search module: control data provisioning, stopwords, filter rules and runtime behavior of the shop search.
The configuration of the search module is currently not yet directly available in OSB – neither via a graphical interface nor via code-based input. At the moment, setup can only be carried out via WEBSALE.
The option to **configure via code** will be provided shortly. We kindly ask for your patience until then and will inform you as soon as this option becomes available.
Until then, please share your desired settings with your WEBSALE contact so that the adjustments in the search module can be made for you.
***
## Import configuration & search module configuration
For the WEBSALE | search module to work correctly, both the associated import module ("provisioning") and the search module itself must be configured.
Both areas are closely linked but perform different tasks.
### Import module of the search
In the import module, the **data for the search is provided**.
Here it is defined which data is imported and made available – for example product and category data fields, JSON files for content such as terms and conditions, contact or FAQ, stopwords, and other search parameters.
However, it is not enough to merely provide the data.
In the search module itself, it must additionally be configured whether and how this data should be taken into account. If the provided data is not activated or included in the search module, it has no influence on the search function.
### Search module
The search module defines how the provided data is taken into account during the search in the shop – that is, at runtime.
This means that, for example, imported stopwords, filter rules, or data fields are actively used in the search and filter logic.
Only the combination of provided data (import module) and its activation in the search module ensures that the desired search configuration is complete and effective.
***
## Data feed in the Dataflow Manager
The data feed forms the basis for the import module.
The data feed is created in the online service area of the [DataflowManager](https://websale.atlassian.net/wiki/spaces/Doku/pages/2124972064/DataFlowManager) and contains all product information that is taken into account in the search index.
All product data that is to be searched, filtered, or sorted is provided via the data feed. To this end, all relevant product fields must be included in the Dataflow Manager – e.g. name, description, categories, price, stock level, attributes, etc. The import module then accesses this feed and converts the contained data into the internal JSON format for the Elasticsearch index.
***
## Configuration hierarchy (from v1.12.x / v1.11.x)
The configuration hierarchy described below is available from the plugin versions **websale\_search v1.12.x** and **elasticsearch\_manager v1.11.x**. The merge logic applies equally to the search module and the import module.
From these versions on, both modules support a three-level configuration hierarchy: `global_configs` → `language_configs` → `subshop_configs`. This allows settings to be defined once at the global level and, if required, to be selectively overridden at the subshop level. This avoids redundancies in the configuration.
At the top level, generally only infrastructure aliases, for example for database connections or index names, are defined. These are included in the subordinate blocks via YAML aliases (`*/`).
There are currently still some exceptions to this. In `elasticsearch_manager`, `datafeed` is still configured directly at the top level. In `websale_search`, the same applies to `filter_config` and `suggest_config`. All other settings follow the three-level model via `global_configs`, `language_configs`, and `subshop_configs`.
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
x-database: &database
base_url: http://websale-search-es-connector-es-http:9200
connections_per_node: 15
timeout: 30
retries: 10
retry_timeout: true
x-keydb: &keydb
host: websale-search-keydb-connector
port: 6379
mapping:
deutsch: 0
englisch: 1
x-indices: &indices
product: product
category: category
completion: completion
content: content
statistics: statistics_data
archive: statistics_archive
suggest: aggregated_statistics
```
### Global configuration (`global_configs`)
`global_configs` forms the lowest level of the hierarchy. Values defined here apply to all subshops unless they are overridden at a higher level.
**Search module**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
database: *database
keydb: *keydb
indices: *indices
global_configs:
search_config: {...}
fields_config: {...}
suggest_config: {...}
filter_config: {...}
language_configs: {...}
subshop_configs: {...}
```
**Import module**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
database: *database
keydb: *keydb
indices: *indices
global_configs:
variant_fields: {...}
index_configs: {...}
language_configs: {...}
subshop_configs: {...}
```
### Language configuration (`language_configs`)
`language_configs` forms the middle level of the hierarchy. Here, configurations can be defined for language groups that apply to all subshops of that language. They can only be overridden by explicit subshop configurations.
**Search module**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
language_configs:
de:
lemmatization: {...}
stopwords_filter: {...}
fuzzy_filter: {...}
punctuation_filter: {...}
en:
lemmatization: {...}
stopwords_filter: {...}
fuzzy_filter: {...}
punctuation_filter: {...}
```
**Import module**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
language_configs:
de:
lemmatization: {...}
stopwords: {...}
synonyms: {...}
en:
lemmatization: {...}
stopwords: {...}
synonyms: {...}
```
### Subshop configuration (`subshop_configs`)
`subshop_configs` forms the highest level of the hierarchy. Here, any configuration parameter can be explicitly overridden for an individual subshop.
The `language` key in `subshop_configs` links the respective subshop to the `language_configs` block associated with its language.
**Search module**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
subshop_configs:
deutsch:
language: de # loads the "de" config from language_configs
keyword_mappings: {...}
wssearchdata_mappings: {...}
englisch:
language: en # loads the "en" config from language_configs
keyword_mappings: {...}
wssearchdata_mappings: {...}
```
**Import module**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
subshop_configs:
deutsch:
language: de # loads the "de" config from language_configs
datafeed_url: https://www.example-datafeed.de/example/download/path/file-deutsch.csv
englisch:
language: en # loads the "en" config from language_configs
datafeed_url: https://www.example-datafeed.de/example/download/path/file-englisch.csv
```
***
## Configuration of the import module
### Data feed configuration
The assignment and processing of the feed is defined in the `datafeed` section of the import module configuration. Here, format, encoding, storage paths, and the field assignments required by the search index during import are defined.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
datafeed:
format: csv
encoding: ISO-8859-1
chunk_size: 1000
dir_path: /data/subshop_data
remove_na_values: true
new_product_days: 365
invalid_docs_max: 0
log_percent: 10
product_id: number
base_id: prodindexbase
is_base_product: isbaseproduct
creation_date: creationdate
api_store_id: StoreId
es_store_id: storeid
inventory: inventory
inventory_active: inventory-active
inventory_type: inventory-type
category_str: allcategories
category_ids: catids
all_category_ids: allcatids
category_separator: "/"
value_separator: ">"
field_separator: "\t"
index_category_hierarchy: false
normalize_negative_prices: true
```
**Parameter description**
| **Parameter** | **Description** |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `format` | File format of the data feed, e.g. `csv`. Currently, only `csv` is supported. |
| `encoding` | Character encoding of the feed, e.g. `ISO-8859-1`. In v8s, currently only ISO encodings are supported, i.e. `utf-8` is not supported. |
| `chunk_size` | Number of rows per processing step (chunk). Default value: `1000`. |
| `dir_path` | Path for the automatically generated temporary JSON files that serve as a buffer during import, e.g. `/data/subshop_data`.
The path is specified by WEBSALE when the search module is set up and cannot be changed. |
| `remove_na_values` | Removes invalid or empty values from the feed.
- `true` → Empty or invalid values are removed during import.
- `false` → Values are preserved and imported into Elasticsearch. |
| `new_product_days` | Defines how many days a product is considered "new" after its creation, e.g. `365`. This information is needed to use sortings or filters for "newest products". |
| `invalid_docs_max` | Maximum number of invalid rows before the import process is aborted. A value of `0` means that the process stops at the first invalid row.
For the process to continue, the errors must be fixed. |
| `log_percent` | Threshold in percent at which the progress of the import is logged. Example: `10` means that a log entry is created after every 10 % of the processed data.
The logs are currently only available to WEBSALE AG and can be sent on request. |
| `product_id` | CSV column name that points to the product data field containing the unique product number. The technical field name of the product data field that contains the product number must be specified, e.g. `number` |
| `base_id` | Base product ID. The technical field name of the product data field that contains the product number must be specified, e.g. `prodiindex` |
| `is_base_product` | The technical field name of the product data field from the data feed must be specified that contains the information whether it is a base product. |
| `creation_date` | The technical field name of the product data field from the data feed must be specified that contains the timestamp of the product's creation. |
| `api_store_id` | Name of the stock ID from the [REST stock](https://websale.atlassian.net/wiki/spaces/Doku/pages/1819869432/REST+Lagerbestand) interface, e.g. `StoreId` |
| `es_store_id` | Stock ID. The technical field name of the product data field from the data feed must be specified that contains this information, e.g. `storeid` |
| `inventory` | Indicates the stock of a product.
The technical field name of the product data field from the data feed must be specified that contains this information, e.g. `inventory` |
| `inventory_active` | Indicates whether a product has stock management activated.
The technical field name of the product data field from the data feed must be specified that contains this information, e.g. `inventory-active` |
| `inventory_type` | Indicates whether stock management is static or dynamic.
The technical field name of the product data field from the data feed must be specified that contains this information, e.g. `inventory_type` |
| `category_str` | Contains all category strings (category names) of a product.
If the product is assigned to only one category, it is of course only that one category name. With multiple category assignments, however, all can be transferred.
The technical field name of the data field from the data feed must be specified that contains this information, e.g. `allcategories` |
| `category_ids` | Contains the category IDs of the product.
If the product is assigned to only one category, it is of course only one index. With multiple category assignments, however, all indexes can be transferred.
The technical field name of the data field from the data feed must be specified that contains this information, e.g. `allcatids` |
| `all_category_ids` | Contains *all* category IDs of the product including the breadcrumb, if a product is assigned to multiple categories.
If the product is assigned to only one category, it is of course only one index. With multiple category assignments, however, all indexes can be transferred.
The technical field name of the data field from the data feed must be specified that contains this information, e.g. `catids` |
| `category_separator` | If products are located in multiple categories, the separator, e.g. `/`, must be specified here to correctly separate the data from each other. |
| `value_separator` | For values within a field, e.g. breadcrumb separator for the category; can be used for any field, e.g. ingredients for foods.
Separator for multi-valued content per field. During import, the values of the field are split into individual entries based on this separator (e.g. for category breadcrumbs or ingredients). The separator must be coordinated with the feed generation; it must not appear unmarked in the actual value (ensure escaping/quoting in the feed if necessary). |
| `field_separator` | Character that separates the columns in the CSV data feed. The default is the tab (TAB), recommended for tab-CSV files. Other separators (e.g. `;` or `,`) are possible but must match the actual feed structure. |
| `index_category_hierarchy` | Defines whether the import module builds the category hierarchy automatically. With `true`, it is sufficient for products to be assigned only to the lowest category; they are then also found in the parent categories. With `false`, the hierarchy is not created automatically. Applies globally to all subshops.
Default: `false` |
| `normalize_negative_prices` | (De)activates the normalization of negative prices. When activated, negative prices are normalized to 0.0. |
### Subshop configuration in the import module
In this section, all subshop-specific settings for the import module are defined.
Each subshop is configured as its own configuration block under the `subshop_configs` section.
This configuration defines which data is imported and provided per subshop. This allows the search module to later access the appropriate data per subshop in a targeted manner and control the search individually.
**Standard configuration for the German subshop**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
subshop_configs:
deutsch:
nlp_lang: de
datafeed_url: http://content..websale.net/search/websale_search.csv
variant_fields:
enabled: true
fields:
- color
- size
index_configs:
product:
enabled: true
custom_fields:
- name: keyword_field123
type: keyword
- name: template_field456
type: template
- name: timestampcreatedat
type: date
format: strict_date_optional_time||epoch_second
- name: float_field789
type: double
category:
enabled: true
custom_fields:
- name: cat_descr
type: template
custom_config:
search_fields:
- field: cat_str
boost: 2
- field: cat_str_path
boost: 1.5
display_fields:
- field: cat_id
- field: cat_id_path
- field: cat_str
- field: cat_str_path
content:
...
completion:
enabled: true
fields:
- name: name
validate: False
- name: descr
validate: True
stopwords: {...} # see section "Tolerance for ignoring stopwords (stopwords)"
synonyms: {...} # see section "Synonyms (synonyms)"
lemmatization: {...} # see section "Grammatical inflection (lemmatization)"
englisch:
{...}
```
**Parameter description**
| **Parameter** | **Description** |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nlp_lang` | The `nlp_lang` parameter defines the language in which the textual preparation of the search data takes place.
Language-specific models and rules from the NLP libraries [spaCy](https://spacy.io/) and [Simplemma](https://adbar.github.io/simplemma/) are used.
These ensure that the search data is analyzed and processed in a language-appropriate way during import – for example with regard to word stems, base forms (lemmas), and stopwords.
Currently available languages:
- German (`de`) = default
- English (`en`)
- Spanish (`es`)
- French (`fr`)
- Italian (`it`)
- Dutch (`nl`)
- Portuguese (`pt`)
- Danish (`da`)
- Czech (`cs`)
- Polish (`pl`)
- Finnish (`fi`)
- Indonesian (`id`)
- Slovak (`sk`)
- Turkish (`tr`)
- Swedish (`sv`)
- Norwegian Bokmål (`nb`) |
| `datafeed_url` | URL of the data feed. Set up and provided by WEBSALE support. |
| `variant_fields` | List of technical product data fields, e.g. color (`color`), size (`size`), etc., that describe variants of a product (see section [Variant Fields](#variantenfelder-für-filter-variant_fields)). |
| `enabled` | Links base products and their variants during import. |
| `fields` | Technical names of the variant fields of a product (always in lowercase) |
| `index_configs` | Index-specific configurations |
| `product` | Main index for the product search. Contains the product data fields for the search index. |
| `enabled` | Activates the creation of this index during import |
| `custom_fields` | Individually defined product data fields that are additionally included in the search index. Specify the technical name of the product data field. |
| `name` | Technical name of the product data field (always in lowercase) |
| `type` | Data type of the field. Available types: `text`, `keyword`, `integer`, `float`, `double`, `date`, `boolean`, `template`.
`template` is a special field type for text fields that should be both searchable and filterable. |
| `category` | Index for the category search. Enables searching categories as a standalone index. If a category index was created during import, it can be activated in the search module configuration. |
| `enabled` | Activates the creation or use of this index. Must be set to `true` both in the import configuration and in the search module configuration. |
| `custom_fields` | Individually defined fields to be additionally included in the category index, analogous to `product` (see custom\_fields section of the product index). By default, only the standard category fields are included (IDs and name). Each field is specified with `name` (technical field name, always lowercase) and `type` (data type, e.g. `text`, `keyword`, `template`). |
| `custom_config` | Configuration block for the category search. Here, it is defined which fields are searched and which are returned in the response. This key is analogously adopted for future additional indexes. |
| `search_fields` | List of fields that are searched during a category search (analogous to `product`). Should always contain at least the fields `cat_str` and `cat_str_path`. A `boost` value can be specified per field to control the weighting. |
| `field` | Technical name of the field to be searched. Available by default: `cat_str`, `cat_str_path`. |
| `boost` | Weighting factor for the field during search. Higher values increase the relevance of hits in this field. |
| `display_fields` | List of fields returned in the search response (analogous to `product`). At least `cat_id` is required. Fields available by default: `cat_id`, `cat_id_path`, `cat_str`, `cat_str_path`. |
| `field` | Technical name of the field to be included in the response. |
| `content` | Main index for the search over content pages such as legal notice, privacy, terms and conditions, etc.
You can find more information in the section [content](#inhaltsseiten-in-den-suchindex-aufnehmen). |
| `completion` | Index for suggestions (autocomplete) |
| `enabled` | Activates the creation of this index during import |
| `fields` | List of product data fields from the search index used for suggestions. |
| `stopwords` | Definition of the stopword list.
You can find more information in the section [stopwords](#toleranz-für-das-ignorieren-von-stoppwörtern-stopwords).
You can find more information about activating the function in the search module in the section [stopwords\_filter](#toleranz-für-das-ignorieren-von-stopwörtern-stopwords_filter). |
| `synonyms` | Definition of manual synonym lists.
More information in the section [synonyms](#synonyme-synonyms). |
| `lemmatization` | Configuration of grammatical inflections.
You can find more information in the section [lemmatization](#grammatikalische-flexion-lemmatization).
You can find more information about activating the function in the search module in the section [lemmatization](#grammatikalische-flexion-lemmatization-2). |
#### Tolerance for ignoring stopwords (stopwords)
Stopwords are less meaningful words (e.g. articles, simple prepositions) that can be ignored when evaluating search queries in order to reduce irrelevant matches.
Whether this ignore logic is applied at runtime is controlled by the search module. Which words are treated as stopwords, excluded (whitelist), or additionally included (blacklist) is defined by the import module.
This section defines how the search function deals with frequently occurring, low-meaning words ("stopwords"). The basis is the default list from spaCy, which contains common function words like *the, a, with, from*, etc.
This list can be individually adjusted with optional whitelist and blacklist entries:
* The whitelist removes words from the spaCy stopword list so that they are not ignored and are considered during search.
* The blacklist adds words to the spaCy list so that they are filtered out during search. (If a word is blacklisted that is already contained, the effect remains unchanged.)
Optionally, your own `.txt` file with stopwords can be used. If this is to be stored externally – e.g. on a customer system – technical coordination for including the file is required.
For the configured stopwords to actually be taken into account in the search process, the parameter `stopwords_filter.enabled: true` must be activated in the **search module** → *see* section "Stopword filter in the search module".
**Standard configuration** `stopwords`
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
stopwords:
path: "" # optional: path to your own .txt, otherwise spacy default
whitelist: # terms that should NOT be treated as stopwords
- mit # important for product characteristics (e.g. jacket with hood)
- ohne # important for pet food (e.g. without grain)
- für # important for target groups (e.g. for women)
- in # important for colors/sizes (e.g. in blue, in size 40)
- und # important for combinations (e.g. chicken and rice)
blacklist: # additional stopwords to be removed
- der
- die
- das
- ein
- eine
- einer
- eines
- einem
- einen
- bei
- nach
- von
- zu
- zum
- zur
- auch
- oder
```
**Parameter description** `stopwords`
| **Parameter** | **Description** |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path` | Path to your own `.txt` file with stopwords (one word per line). Example: `/data/stopwords_de.txt`
If no file is specified, the default list from [spaCy](http://spacy.io) is used. |
| `whitelist` | Words that should **not** be treated as stopwords (exceptions to the default list).
Suitable for domain-relevant terms such as "mit", "ohne", "für", "in", "und". |
| `blacklist` | Additional words to be **removed** as stopwords (in addition to the default list from [spaCy](http://spacy.io)).
Typical: articles/prepositions such as "der", "die", "das", "ein", "eine", "einer", "eines", "einem", "einen", "bei", "nach", "von", "zu", "zum", "zur", "auch", "oder". |
The function must also be activated for the [search module](#toleranz-für-das-ignorieren-von-stopwörtern-stopwords_filter).
#### Synonyms (synonyms)
The synonym function makes it possible to link terms with each other in the search. This means that when a term is entered, hits for equivalent or related terms also appear.
Synonyms can be defined either bidirectionally ("Jacke" = "Jacket") or unidirectionally ("Turniersakko" → "Turnierjacke"). Optionally, synonym lists can be stored as a file or maintained directly in the configuration.
By default, no synonyms are stored. The function becomes active as soon as either a synonym list (`path`) is specified or manual synonyms (`clouds`) are defined.
**Example configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
synonyms:
path: ""
clouds:
- src: # Example 1
- trenchcoat
- kutte
- caban
- janker
target:
- mantel
- jacke
mode: bi
- src: # Example 2
- kängoro
- kängguhru
- kengooroo
target: känguru
mode: uni
```
* **Example 1 (`mode: bi`)** The terms *"trenchcoat"*, *"kutte"*, *"caban"*, *"janker"*, *"mantel"* and *"jacke"* are linked bidirectionally. A search for one of these terms also leads to hits that contain one of the other terms. For example, a search for *"Janker"* also returns results with *"Mantel"* or *"Trenchcoat"*, and vice versa.
* **Example 2 (`mode: uni`)** The terms *"kängoro"*, *"kängguhru"* and *"kengooroo"* are mapped unidirectionally to the term *"känguru"*. A search for one of the spelling variants leads to hits with *"känguru"*, but not vice versa. This mode is particularly suitable for typos, spelling variants, or unified terms.
**Parameter description**
| **Parameter** | **Description** |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `path` | Optionally, a TXT file with synonyms can be stored (one word per line). The path to the `txt` file is specified in the parameter.
Example: `/data/stopwords_de.txt`
Changes to the file require reindexing.
If the file is to be stored externally – e.g. on a customer's server – separate technical coordination is required to ensure access to this file. |
| `clouds` | List of manually defined synonym groups. Each group describes a relationship between source and target terms. |
| `src` | Source term(s) to be replaced or linked. Can be specified as a single string or as a list. |
| `target` | Target term(s) that are referenced. This can be specified as a single string or as a list. |
| `mode` | Linking mode:
- `uni` → unidirectional (only `src → target`, i.e. when `src` is entered, `target` is searched, not vice versa)
- `bi` → bidirectional (all terms within `src` and `target` are mutually considered synonyms) |
**Note:** After changes to synonyms, the data feed generation must be started manually so that reindexing takes place.
#### Grammatical inflection (lemmatization)
This section defines whether and for which fields grammatical word forms are reduced to their base form during import. This enables the search to also recognize linguistic variants – for example, that "rote Hemden", "rotes Hemd" or "Hemd in Rot" mean the same term.
The function improves linguistic recognition and provides more natural search results. It should be activated for descriptive text fields (e.g. *name*, *descr*) but deactivated for technical fields (e.g. *product\_id*, *sku*).
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
lemmatization:
enabled: true
language: de
fields:
- name
- descr
```
* Grammatical base-form recognition is activated (`enabled: true`).
* German language logic is used (`language: de`).
* The fields `name` and `descr` are reduced to their base forms during import.
* This allows the search to also recognize grammatically or word-order-varying terms (e.g. "rotes Hemd" ↔ "Hemd in Rot").
**Parameter description**
| **Parameter** | **Description** |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates (`true`) or deactivates (`false`) the grammatical reduction of search terms to their base form.
The basis are the language-specific word stems and models of the NLP libraries [*spaCy*](https://spacy.io/) and [Simplemma](https://adbar.github.io/simplemma/).
When deactivated, an exact-word search is performed without linguistic unification. |
| `language` | Defines the language for which the lemmatizer is applied. Currently available:
- German (`de`) = default
- English (`en`)
- Spanish (`es`)
- French (`fr`)
- Italian (`it`)
- Dutch (`nl`)
- Portuguese (`pt`)
- Danish (`da`)
- Czech (`cs`)
- Polish (`pl`)
- Finnish (`fi`)
- Indonesian (`id`)
- Slovak (`sk`)
- Turkish (`tr`)
- Swedish (`sv`)
- Norwegian Bokmål (`nb`)
Depending on the selected language, the corresponding language models from [*spaCy*](https://spacy.io/) are used to correctly recognize grammatical variants. |
| `fields` | Defines which data fields from the import are analyzed linguistically and lemmatized. The technical field names of the data feed must be specified.
By default, `name` (product name) and `descr` (product description) are stored.
Changes to this setting require a new import. |
The function must also be activated for the [search module](#grammatikalische-flexion-lemmatization-2).
#### Categories
**Fixed fields in the category index**
| **Field** | **Description** |
| -------------- | ------------------------------------------------------------------------------------ |
| `cat_id` | Category ID. |
| `cat_str` | Category name. |
| `cat_id_path` | Category ID path. |
| `cat_str_path` | Full category path as a string. |
| `cat_image` | Category image (optional). |
| `sort_field` | Automatically populated from `cat_str_path` (can be overridden via `custom_fields`). |
#### Include content pages in the search index
In addition to products (and possibly categories), static content pages can also be included in the search – e.g. "About us", terms and conditions, legal notice, or privacy policy. To do so, the content import is activated in the **import module** (`content.enabled`) and the connection to the respective shop API (VX or v8) is configured.
Optionally, the pages to be indexed can be restricted in a targeted way (e.g. via `included_content`).
`Category` and `Content` are special indexes that, unlike the product index, cannot be freely extended with new fields. Both work with a fixed set of fields (see below). The `custom_fields` parameter here serves exclusively to override or adjust the Elasticsearch mapping of existing fields (e.g. analyzer, field type). It was adopted analogously from the product index for other indexes, but does not extend the indexing with new data fields.
**Fixed fields in the content index**
| **Field** | **Description** |
| ------------ | ----------------------------------------------------------------------------- |
| `source` | Path to the content page (e.g. `content/gtc.htm`). |
| `title` | Page title. |
| `content` | Extracted text content of the page. |
| `sort_field` | Automatically populated from `title` (can be overridden via `custom_fields`). |
**Standard configuration** of the [demo shop](https://demo.shop.websale.biz/)
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
content:
enabled: true
custom_fields: # analogous to product/category; by default only 'title' and 'content' are included
- name: field_name
type: field_type
custom_config:
host: demo.shop.websale.biz
user: "example@websale.de"
password: ""
endpoint: seo/urls/templates
params:
size: 300
sort: resourceIdentifier:asc
path_field: path
source_field: resourceIdentifier
content_id: "wsMainContent"
included_content:
- "content/aboutUs.htm"
- "content/gtc.htm"
- "content/imprint.htm"
- "content/privacy.htm"
- "content/return.htm"
- "content/returnInquiry.htm"
# the following keys are not relevant for VX
api_version: v8
base_path: /api/
auth_url: /authent/login/
shop_url: www.myshop.de
```
**Parameter description**
| **Parameter** | **Description** |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates the import and indexing of static content pages for the search. |
| `custom_fields` | Optional adjustment of the Elasticsearch mapping for the content index (analogous to `Product`/`Category`). This allows existing fields in the mapping to be overridden or extended. Only changes the mapping! The indexing of `Content` and `Category` is fixed and cannot be extended with new data fields via configuration. |
| `custom_config` | Technical additional configuration for importing and reading out static content (differs between VX and v8). |
| `host` | Host of the API.
- **V8s:** Host of the v8 API (e.g. `websale.de`)
- **New version:** corresponds to the shop-ID domain (e.g. `common-id.shop.websale.net`). |
| `user` | Username for authentication with the Auth API. |
| `password` | Password for authentication with the Auth API. |
| `endpoint` | API endpoint from which the SEO template/URL data is loaded.
- **V8s:** `seo/templates`.
- **New version:** `seo/urls/templates` |
| `params` | Optional URL parameters for the API call. Only for the **new version**.
- `size` - Maximum response size (max. 300 SEO URLs per request)
- `sort` - Sorting of the response items (e.g. `resourceIdentifier:asc`) |
| `osbcommonid` | **V8s only.** Common ID for OSB (if required for the respective environment). |
| `path_field` | Field name from the API response that contains the path of the page (e.g. `/ueber-uns`).
- **V8s:** `terms`
- **New version:** `path` |
| `source_field` | Field name from the API response that contains the source/template reference (e.g. `content/aboutUs.htm`).
- **V8s:** `template`
- **New version:** `resourceIdentifier` |
| `content_id` | Optional ID of an HTML container from which the relevant page content is extracted (e.g. `wsMainContent`).
If not set, `` is read by default; if not present, the entire page (including header/footer) is taken over. |
| `included_content` | Optional allow list: only imports/indexes the "source" entries specified here (e.g. individual templates/content files).
Without specification, all available pages are considered. |
| `api_version` | **V8s only.**
Version of the shop API (e.g. `v8`).
In the new version, this parameter is omitted, since a suitable default value is stored. |
| `base_path` | **V8s only.**
Base path for interfaces (e.g. `/api/`).
In the new version, this parameter is omitted, since a suitable default value is stored. |
| `auth_url` | **V8s only.**
Endpoint of the Auth API (e.g. `/authent/login/` or with Common ID).
In the new version, this parameter is omitted, since a suitable default value is stored. |
| `shop_url` | **V8s only.**
Public shop URL.
In the new version, `host` generally corresponds to the shop URL, or is sufficient for it. |
***
## Configuration of the search module
### Search suggestions (suggest\_config)
**Base configuration** `suggest_config`
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
suggest_config:
query:
enabled: true
fuzziness: 0
size: 10
product:
enabled: true
size: 8
category:
enabled: true
size: 5
content:
enabled: true
size: 5
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query` | Configuration for text-based search suggestions (autocompletion of the search input). |
| `product` | Configuration for product suggestions. The product index is the basis (see import configuration). |
| `category` | Configuration for category suggestions. The category index is the basis (see import configuration). |
| `content` | Configuration for content page suggestions. The content index is the basis (see import configuration). |
| `enabled` | Activates (`true`) or deactivates (`false`) the respective suggest type. Deactivated types are not displayed in the frontend, even if the corresponding HTML components are present. |
| `size` | Number of search suggestions for the respective suggest type. |
| `fuzziness` | Controls the error-tolerant search method (only for type `query`) that compensates for typos or spelling deviations within the suggest.
The allowed edit distance within the suggest (replace, insert, delete) per word can be configured:
- `0` → **no** error tolerance (must match exactly, after analysis/normalization)
- `1` → up to **1** edit allowed
- `2` → up to **2** edits allowed
- `AUTO` → adjusts the distance to the word length: word length 1 - 2 → 0, 3 - 5 → 1, ≥6 → 2 (for 1 - 2 characters no tolerance, for 3 - 5 exactly 1 edit, from 6 up to 2 edits)
- `AUTO:x,y` → own thresholds: up to x-1 characters → 0, from x to y-1 → 1, from y → 2. Example `AUTO:4,8`: lengths ≤4 → 0, 5 - 8 → 1, ≥9 → 2 |
The basis of the suggest types `product`, `category` and `content` is the respective index. These must first be activated and configured in the import module so that the corresponding suggestions are available at runtime (see [Categories](#kategorien), [Content pages](#inhaltsseiten-in-den-suchindex-aufnehmen) as well as the [completion index](#subshopkonfiguration-im-importmodul)).
### Filter (filter\_config)
**Base configuration** `filter_config`
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
filter_config:
filter_size: 100
doc_count: 1
default_min: 0
default_max: 1000
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `filter_size` | Number of filter options per filter |
| `doc_count` | Minimum number of documents in which a value must occur in order to be available as a filter option |
| `default_min` | Fallback for range filters, minimum value |
| `default_max` | Fallback for range filters, maximum value |
### Subshop configuration for the search module
The configuration of the search module is defined per subshop and is stored under the subshop ID as key.
**Overview example**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
subshop_configs:
{subshop_id}: # e.g. 01-aa: or 83-it: (lowercase)
search_config: # base configuration of the search types (exact, prefix, fuzzy …)
{...}
fields_config: # field definitions and weightings
{...}
index_configs: # index settings
{...}
punctuation_filter: # handling of special characters
{...}
fuzzy_filter: # thresholds for fuzzy search
{...}
stopwords_filter: # words to be ignored
{...}
lemmatization: # base-form reduction
{...}
```
### Base configuration of the search module (search\_config)
The base configuration defines which search types are active and how search terms are evaluated.
These settings control whether search terms should be found exactly, partially, fuzzy, or as parts of words.
Each search type can be activated, weighted, and combined separately.
**Basic structure**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
search_config:
mode: add
exact:
{...}
prefix:
{...}
wildcard:
{...}
ngram:
{...}
fuzzy:
{...}
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mode` | Defines how the field boosts of the individual search types are combined (additively or multiplicatively). |
| `exact` | Configuration for exact matches of search terms (see section [Exact Search](#exakte-suche-exact)). |
| `prefix` | Configuration for prefix searches, in which the search term appears at the beginning of a word (see section [Prefix Search](#präfix-suche-prefix)). |
| `wildcard` | Configuration for wildcard searches, in which the search term can occur anywhere in the word (see section [Wildcard Search](#wildcard-suche-wildcard)). |
| `ngram` | Configuration for N-gram searches, in which parts of the search term match within a word (see section [Ngram Search](#teilwortsuche-n-gram-suche-ngram)). |
| `fuzzy` | Configuration for error-tolerant (fuzzy) searches that also take slightly deviating spellings into account (see section [Fuzzy Search](#fehlertolerante-suche-levenshtein-distanz-fuzzy)). |
#### Exact search (exact)
The exact search only returns hits if the search term matches the stored word exactly. It thus represents the most precise form of search and is usually used as the basis or supplement to other search types. Hits from the exact search are typically assigned a higher relevance, since they represent a complete match.
This search type should always remain activated, as it ensures that with identical spellings (e.g. exact product names, brands, article numbers) the most relevant results appear first.
The weighting relative to other search types can be fine-tuned via the *boost value*.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
exact:
enabled: true
boost: 2.0
tie_breaker: 0.3
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | Activates (`true`) or deactivates (`false`) the exact search. Should generally remain activated. |
| `boost` | Relevance factor for exact hits. A higher value strengthens the weighting of exact matches in the overall ranking (recommended: 2.0 – 3.0). |
| `tie_breaker` | Determines how strongly multiple hits for the same search term in multiple fields affect the score.
A value of 0.1 – 0.3 is usually sensible to slightly increase the relevance without dominating it. |
#### Prefix search (prefix)
The prefix search returns hits when the search term is at the beginning of a word. It is typically used to enable hits during input or to recognize word beginnings – for example, entering "schn" also returns results such as *Schneider*, *Schnürsenkel*, or *Schnalle*.
This search type sensibly complements the exact search, since it reacts more flexibly to partial terms without giving up precision entirely. It is particularly useful in combination with autocomplete functions and suggest components.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
prefix:
enabled: true
boost: 1.75
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates (`true`) or deactivates (`false`) the prefix search. |
| `boost` | Relevance factor for prefix hits.
Recommended range: 1.0 – 2.0, to slightly prefer word beginnings without displacing exact hits. |
#### Wildcard search (wildcard)
The wildcard search finds hits when the search term occurs anywhere within a word. It is significantly more flexible than the prefix search, since it also recognizes word components – for example, entering "hose" returns hits such as *Jeanshose*, *Arbeitshose*, or *Strumpfhose*.
This search type is particularly suitable for cases where users do not know the exact word beginning, e.g. for compound terms, variants of product names, or technical designations.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
wildcard:
enabled: true
boost: 1.5
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates (`true`) or deactivates (`false`) the wildcard search. Recommended when partial terms or word components are relevant. |
| `boost` | Relevance factor for wildcard hits.
Recommended range: 0.5 – 1.5, to allow flexible hits while still prioritizing exact matches. |
#### Partial-word search / N-gram search (ngram)
The N-gram search enables hits when a part of the search term occurs within a word – regardless of whether the term appears at the beginning, in the middle, or at the end. It is based on splitting words into small units (so-called *N-grams*) that are generated during index construction.
This search type is particularly suitable for technical terms, model numbers, article codes, or compound words for which the user often only knows parts of the term. Example: The input "AB12" also finds *AB1234-X* or *XX-AB12-Z*.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
ngram:
enabled: true
boost: 1.25
tie_breaker: 0.3
minimum_should_match: 80%
```
**Parameter description**
| **Parameter** | **Description** |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates (`true`) or deactivates (`false`) the N-gram search. |
| `boost` | Relevance factor for partial-word hits.
Recommended range: 0.8 – 1.5, to allow supplementary hits without displacing exact results. |
| `tie_breaker` | Determines how strongly multiple hits in different fields affect the total score.
Values between 0.1 – 0.3 are usually sensible. |
| `minimum_should_match` | The parameter can be used to control what percentage of N-grams must match to count as a hit – this improves the result quality.
Recommended: 60 – 80 % for a good balance between hit rate and precision. |
#### Error-tolerant search & Levenshtein distance (fuzzy)
The fuzzy search is an error-tolerant search method that compensates for typos or spelling deviations. The basis is the Levenshtein distance, which counts how many edit steps (insert, delete, replace) separate two words.
Examples:
* "Haus" → "Maus" = distance 1 (1 letter replaced)
* "Haus" → "Huas" = distance 2 (letters transposed → replace + replace)
* "Haus" → "Hause" = distance 1 (one letter inserted)
`fuzzy` controls the global error-tolerant search based on the Levenshtein distance. Here, it is defined whether fuzzy is active, what error tolerance (e.g. `AUTO` depending on word length) applies, and how strongly fuzzy hits are weighted in scoring (`boost`, `tie_breaker`).
The configuration generally affects all search terms and fields, unless it is restricted by downstream rules → see [Exceptions to the global fuzzy logic (fuzzy\_filter)](#ausnahmen-zur-globalen-fuzzy-logik-fuzzy_filter)
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
...
fuzzy:
enabled: true
boost: 0.75
tie_breaker: 0.3
fuzziness: AUTO
...
```
* **Fuzzy search activated:** Error-tolerant matches (based on the Levenshtein distance) are active.
* **Weighting:** With `boost = 0.75`, fuzzy hits receive about 75 % of the weight of an exact hit; higher values prioritize fuzzy more strongly, 0 deactivates the boost effect.
* **Cross-field weighting:** `tie_breaker = 0.3` causes additional hits in other fields to contribute about 30 % to the score; smaller values dampen and larger values amplify this multi-field effect.
* **Error tolerance:** `fuzziness = AUTO` adjusts the allowed edit distance to the word length (1 - 2 characters → 0, 3 - 5 → 1, ≥6 → 2).
**Parameter description**
| **Parameter** | **Description** |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates or deactivates the error-tolerant search. With `false`, **no** fuzzy evaluation is performed; settings like `fuzziness`, `boost`, or `tie_breaker` then have no effect. |
| `boost` | Weights the influence of the fuzzy hits in the ranking.
- `1.0` corresponds to neutral (neither downgrading nor upgrading)
- Values `< 1.0` weaken fuzzy compared to exact hits (e.g. `0.75`)
- Values `> 1.0` strengthen fuzzy (e.g. `1.5`)
- `0` means: Fuzzy hits do not influence the scoring (the query can still match, but does not contribute to the score). |
| `fuzziness` | Controls the allowed edit distance (replace, insert, delete) per word.
- `0` → **no** error tolerance (must match exactly, after analysis/normalization)
- `1` → up to **1** edit allowed
- `2` → up to **2** edits allowed
- `AUTO` → adjusts the distance to the word length: word length 1 - 2 → 0, 3 - 5 → 1, ≥6 → 2 (for 1 - 2 characters no tolerance, for 3 - 5 exactly 1 edit, from 6 up to 2 edits)
- `AUTO:x,y` → own thresholds: up to x-1 characters → 0, from x to y-1 → 1, from y → 2. Example `AUTO:4,8`: lengths ≤4 → 0, 5 - 8 → 1, ≥9 → 2 |
| `tie_breaker` | During a search, multiple fields are usually searched simultaneously, for example in the title, brand, and description. The system evaluates each field separately. First, the field with the best match (e.g. the title) always counts.
`tie_breaker` defines how strongly additional hits in the other fields contribute to the overall score.
- With `tie_breaker = 0.0`, **only** the best field counts; hits in other fields provide **no** additional points.
- With a **moderate value** (e.g. **0.2 - 0.4**), the other fields provide **a small bonus**; hits in multiple fields thus become visible without dominating the ranking.
- With **1.0**, **all fields would be fully** added; this is rarely sensible, because weaker hits from long descriptions would otherwise gain too much weight.
**Example** A term matches very well in the title (score 10), moderately in the brand (6), and weakly in the description (3).
- **0.0** → total score ≈ **10** (only title counts).
- **0.3** → total score ≈ **10 + 0.3×(6+3) = 12.7** (title remains leading, the other fields help a little). |
### Data fields
`fields_config` defines which data fields are included in the search index and what they are used for (search, display, filtering, sorting, partial-word search, variants, categories). Changes to this block take effect after restarting the search module.
**Basic structure**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
fields_config:
search_fields:
- {...}
- {...}
display_fields:
- {...}
- {...}
filter_fields:
{...}
sort_fields:
- {...}
- {...}
ngram_fields:
- "..."
- "..."
variant_fields:
- "..."
- "..."
category_field: ""
```
**Parameter description**
| **Parameter** | **Description** |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_fields` | Definition of the fields in which to search (see section [Search Fields](#datenfelder-für-die-suche-search_fields)). |
| `display_fields` | Specification of the fields that are passed to the frontend in the search result (see section [Display Fields](#datenfelder-im-such-response-display_fields)). |
| `filter_fields` | Definition of the available filters and their types in the search frontend (see section [Filter Fields](#datenfelder-für-die-filter-filter_fields)). |
| `sort_fields` | Specification of the fields by which the results can be sorted (see section [Sort Fields](#datenfelder-für-die-sortierung-sort_fields)). |
| `ngram_fields` | Definition of the fields for which the partial-word search (N-gram search) is active (see section [Ngram Fields](#datenfelder-für-teilwortsuche-ngram_fields)). |
| `variant_fields` | Definition of the fields that identify product variants (see section [Variant Fields](#variantenfelder-für-filter-variant_fields)). |
| `category_field` | Specification of the field that contains the category IDs (see section [Category Field](#kategoriefelder-category_field)). |
#### Data fields for the search (search\_fields)
This section defines the fields in which the search is actually performed. Without defined search fields, no content-based search can take place.
The selection of the fields depends on the respective shop; typically, product name, description, category names, brand/manufacturer, or color variants are specified.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
fields_config:
...
search_fields:
- field: name
boost: 3
- field: descr
boost: 2
- field: brand
boost: 1.5
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field` | Name of the data field to be included in the search index and thus also searched.
The technical field name of the data field from the data feed must be specified that contains this information, e.g.
- Product name (`name`)
- Product description (`descr`)
- Brand (`brand`)
- etc. |
| `boost` | Optional relevance factor for the specified data field.
The relevance values range from 1 (low) to 5 (high). Higher values mean that the field is weighted more strongly in the calculation of the search result. |
#### Data fields in the search response (display\_fields)
This section defines which fields are passed to the shop frontend in the search response. These fields can then be used directly in the WebComponents for display.
By default, only the product number or product index is returned, since by default the product data is loaded from the shop database using this index and displayed in the frontend by the WEBSALE template engine.
If the display of the products should not be done via loading the shop database and thus not via the WEBSALE template engine, all fields required for display in the frontend must be added in this section, e.g. price, brand, product image, etc.
For further information, see [Integration into the templates (storefront)](/en/ws-search/integration-in-die-templates-storefront).
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
fields_config:
...
display_fields:
- field: baseprodindex
- field: prodindexbase
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | ---------------------------------------------------------------------------------------- |
| `field` | The technical field name of the product data field from the data feed must be specified. |
#### Data fields for the filters (filter\_fields)
This section defines which filters are available in the search frontend and by which field values it is possible to filter.
The filter system supports different types of filters that are defined directly via the configuration.
Depending on the data type or use case, simple selection filters, price ranges, or user-defined filter logic can be created.
Supported filter types:
* **Terms filter (terms)** - exact values, e.g. brands, colors, categories
* **Range filter (range)** - numeric value ranges, e.g. price, rating
* **Custom filter (custom)** - user-defined conditions (e.g. "salesrank ≤ 1000")
* **Default filter (default)** - automatically active filters (e.g. "only available products")
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
fields_config:
...
filter_fields:
farbgrp:
type: terms
label: Farbe
price:
type: range
label: Preis
salesrank:
type: custom
label: Bestseller
op_type: lte
filter_value: 1000
rating:
type: custom
label: Top bewertet
op_type: gte
filter_value: 4.0
new_field:
type: custom
label: NEU
op_type: eq
filter_value: true
inventory:
# is applied permanently and in a sense "not visibly", ensures
# that the search really only shows "available products"
- type: default
op_type: gt
filter_value: 0
# so the customer can decide to also see products that are not available
- type: custom
label: "Nicht verfügbare Artikel"
op_type: rm
```
* **Terms filter** `farbgrp` for colors.
* **Range filter** `price` for the price (from - to)
* **Custom filter** `salesrank` that filters products with a sales rank (`salesrank`) less than or equal to 1000
* **Custom filter** `rating` that filters products with an average customer rating (`rating`) greater than or equal to 4
* **Custom filter** `new_field` that filters products marked as new (`new_field`)
* **Default filter** `inventory` that filters out all unavailable products by default, combined with a custom filter that makes it possible to remove this default filter and thus also display "unavailable" products.
**Parameter description**
| **Parameter** | **Description** |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `` | Technical field name of the data field from the data feed to which the filter refers, e.g.:
- Color → `farbgrp`
- Price → `price`
- Sales rank → `salesrank`
- Stock → `inventory`
If multiple filters are applied to the same field, a **list** must be configured. Each list entry begins with a hyphen (`-`). An example of this is the filter definition for `inventory` with a default and a custom filter (see above: *code example for the standard configuration*). |
| `type` | Type of the filter: `terms`, `range`, `custom` or `default`.
In addition to customer-specific (dynamic) filters, predefined `custom` and `default` filters are already available by default, e.g. salesrank, rating, new\_field, or inventory. |
| `label` | Optional display name of the filter shown in the frontend |
| `op_type` | Condition type for user-defined filters. Defines how the comparison of the field value should be performed.
Available operators:
- `eq` – *equal* → equal
- `lt` – *less than* → less than
- `lte` – *less than or equal* → less than or equal
- `gt` – *greater than* → greater than
- `gte` – *greater than or equal* → greater than or equal
- `rm` – *remove* → removes a previously set filter (e.g. to cancel a default filter)
Only relevant for filters of `type: custom` and `type: default`. |
| `filter_value` | Comparison value used to check the filter condition. Used together with `op_type` to define which products are included or excluded.
Examples:
- `0` for `inventory` → only shows products with a stock greater than 0
- `true` for `new_field` → only shows products marked as **"new"**
Only relevant for filters of type `custom` and `default`.
Via `filter_value`, [products can also be excluded](#ausschluss-bestimmter-produkte-filter_fields). |
#### Excluding certain products (filter\_fields)
By default, all active products appear in the search.
The exclusion of certain products is done within [filter\_fields](#datenfelder-für-die-filter-filter_fields).
Via `filter_fields`, products can be excluded based on rules without taking them offline. This section describes the configuration in the search module; active rules filter the affected articles out of the search results at runtime.
**Example configuration** `filter_fields`
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
filter_fields:
# Exclusion: product number contains "99", "88" OR "77"
produktnummer:
type: default
op_type: neq
filter_value:
- "99*"
- "*88"
- "*77*"
# Exclusion: category is "Sonderposten" OR "Testkategorie"
category:
type: default
op_type: neq
filter_value:
- "Sonderposten"
- "Testkategorie"
# Exclusion: brand is "adidas" and also, e.g., "adidas originals" OR "Puma"
brand:
type: default
op_type: neq
filter_value:
- "adidas*"
- "Puma"
# Exclusion: Reduced/SALE is "true", i.e. a product is on SALE resp. reduced
is_reduced:
type: default
op_type: eq
filter_value: true
```
**Parameter description** `filter_fields`
Each entry under `filter_fields` is a rule per data field. This rule is checked on every search and decides whether a product may enter the result list or not.
| **Parameter** | **Description** |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filter_value` | Comparison value(s) of the rule, i.e. it is defined **against what** is compared.
Multiple fields under `filter_fields` are linked with **AND** (all rules must be met).
Possible entries / values refer to the data type of the data field in the search index:
- Data type `Text`: Supports text and `*` wildcards (`TEST*` = begins with TEST, `*TEST` = ends with TEST, `*TEST*` = contains TEST). Multiple values can be specified as an array; OR logic within the field.
- Data type `Bool/Number`: no wildcards, specify exactly, e.g. `true`/`false`, `0`/`1`, etc. |
More information about the filter\_fields as well as a complete overview of the parameters can be found in the section [Data fields for the filters (filter\_fields)](#datenfelder-für-die-filter-filter_fields).
#### Data fields for the sorting (sort\_fields)
This block is only configured if the UI component `` is used. In this case, the component reads the entries from `sort_fields` and automatically generates a select box with all configured sort options. Changes to `sort_fields` are thus immediately visible in the frontend – without adjusting the template.
If `use-api="false"` is used, `sort_fields` is not required; the sort UI is then provided manually via the template.
You can find more about the UI component ws-sort-box [here](/en/ws-search/integration-in-die-templates-storefront/webcomponents/ui-komponenten/ws-sort-box).
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
fields_config:
...
sort_fields:
- field: _score
label:
desc: Relevanz
- field: name
label:
asc: Alphabetisch (A-Z)
desc: Alphabetisch (Z-A)
- field: price
label:
asc: Preis absteigend
desc: Preis aufsteigend
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| `field` | The technical field name of the data field from the data feed must be specified that is to be used for sorting. |
| `label` | Definition of the sort labels displayed in the frontend. If no label is specified, the sorting is not created. |
| `asc` | Display name of the descending sort, e.g. price descending |
| `desc` | Display name of the ascending sort, e.g. price ascending |
#### Data fields for the partial-word search (ngram\_fields)
This section defines for which fields the partial-word search (N-gram search) is activated. The partial-word search makes it possible to find hits even with incomplete or partially matching search queries, e.g. the input "jack" also returns results such as Jacke, Jacket, or Jackett.
When building the search index, so-called N-gram tokens are generated for the fields defined here. This means that search terms can already be recognized during input or with inaccurate spelling.
Typical fields are product name, description, or article numbers.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
fields_config:
...
ngram_fields:
- name
- descr
- number
```
**Parameter description**
| **Parameter** | **Description** |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `ngram_fields` | List of technical field names of the data field from the data feed for which the partial-word search is to be activated. |
#### Variant fields for filters (variant\_fields)
This section defines which variant attributes should be considered when determining filter values.
Since calculating filter options (aggregation) over many variant products is performance-critical, the relevant variant fields must be explicitly specified here.
Only the fields defined in this section are included in the filter determination and, in doing so, incorporate the variants of a product.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
fields_config:
...
variant_fields:
enabled: true
fields:
- size
- color
```
* In this example, the fields **color** (`color`) and **size** (`size`) are defined as variant fields.
**Parameter description**
| **Parameter** | **Description** |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates the consideration of variant attributes from the data feed in order to provide them as filter values. |
| `fields` | List of technical field names of variant attributes. |
#### Category fields (category\_field)
In this section, the field name that contains the category IDs (category indexes) is entered.
The field name configured here is used by the search module to correctly determine the context (search result page vs. category page) and to open products in the correct category after a search, filtering, or sorting.
The default value is usually already set and should not be changed.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
fields_config:
...
category_field: catids
```
**Parameter description**
| **Parameter** | **Description** |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `category_field` | Always contains the field name of the data field from the data feed that contains the category IDs. |
### Exceptions to the global fuzzy logic (fuzzy\_filter)
`fuzzy_filter` defines **targeted exceptions** to the global fuzzy logic.
This allows individual terms to always be searched **exactly** (without fuzzy) in order to avoid confusion, and entire **fields** to be excluded from fuzzy (e.g. product IDs). This section serves for fine-tuning when the standard behavior leads to unwanted hits or when certain data fields should always be treated exactly.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
...
fuzzy_filter:
enabled: true
list: []
excluded_fields:
- productnumber
- productid
...
```
* **Fuzzy search activated**: Typos are tolerated according to the global fuzzy tolerance in the `search_config` (e.g. distance depending on word length).
* **No global word exclusions**: The `list` list is intentionally empty, since critical terms vary per shop and should be maintained individually.
* **Fields without fuzzy**: In `productnumber` and `productid`, **no** fuzzy match is performed (exact search on IDs/SKUs).
**Parameter description**
| **Parameter** | **Description** |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates (`true`) or deactivates (`false`) the fuzzy filter.
If `true`, the fuzzy filter is applied, i.e. certain fields or terms (according to `excluded_fields` or `list`) are excluded from the fuzzy search.
If `false`, the fuzzy filter is inactive, and the fuzzy search accesses all fields without restriction. |
| `list` | List of terms that are searched without fuzzy (exactly).
These words are searched exactly, even if there are typos. Useful for critical terms or terms with a high risk of confusion.
**Example:**
`list:`
` - westen`
` - western`
If `westen` and `western` are entered here, no typo tolerance applies to these two words; this prevents confusion (e.g. category *Western* vs. clothing item *Westen*). |
| `excluded_fields` | Fields in which fuzzy should generally not be applied, e.g. `productnumber`, `productid` for exact ID search |
### Special-character handling (punctuation\_filter)
The `punctuation_filter` controls the handling of special characters in search queries and indexed terms. This makes it possible to unify search results and avoid zero hits due to different spellings (e.g. *USB-C*, *USB C*, *USBC*).
An adjustment is required if you want to deviate from the standard behavior – for example, if certain special characters should additionally be preserved (e.g. `&` in brand names) or if additional characters must be removed.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
punctuation_filter:
enabled: true # (de)activation of the function
replace_with_space: # characters to be replaced by a whitespace
- "-"
- "/"
type: black # white = whitelist; black = blacklist
list: # list of characters to be removed/kept (depending on type)
- "_"
- "&"
- "."
```
* **Hyphens (`-`)** and **slashes (`/`)** are replaced by spaces. → "USB-C" = "USB C", "Herren/Hemd" = "Herren Hemd".
* **Underscores (`_`), ampersand (`&`) and periods (`.`)** are removed. → "Winter\_Pullover" = "Winter Pullover", "Jack\&Jones" = "Jack Jones", "PS.5" = "PS5".
* All other characters are preserved.
**Parameter description**
| **Parameter** | **Description** |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | Activates (`true`) or deactivates (`false`) the special-character normalization. |
| `replace_with_space` | List of characters that are not deleted but replaced by a space. Useful for separators that should mark a word boundary (e.g. `-`, `/`). |
| `type` | Defines how the list is interpreted:
- `black` = blacklist → Only the specified characters are removed; all others are preserved.
- `white` = whitelist → Only the specified characters are preserved; all others are removed. |
| `list` | The specific character list that is removed or kept depending on `type`. |
### Tolerance for ignoring stopwords (stopwords\_filter)
The configuration in the search module only defines **whether** the stopword list defined during import is taken into account during query evaluation.
With `stopwords_filter`, the ignoring of stopwords at runtime is switched on or off: If active, terms from the stored list are removed before matching, while words from the whitelist are **not** removed and are thus evaluated normally.
The compilation of the stopword list itself is **not** done in the search module, but entirely in the [import module](#toleranz-für-das-ignorieren-von-stoppwörtern-stopwords).
**Standard configuration** `stopwords_filter`
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
stopwords_filter:
enabled: true
```
**Parameter description** `stopwords_filter`
| **Parameter** | **Description** |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates (`true`) or deactivates (`false`) the tolerance for ignoring stopwords.
Only sensible in combination with a maintained stopword list from the import. |
### Grammatical inflection (lemmatization)
This section defines whether and in which language search terms are reduced to their grammatical base form during the search. This allows the system to recognize that different word forms – for example "rote Hemden", "rotes Hemd" or "Hemd in Rot" – mean the same term.
The function improves semantic recognition and provides more natural search results. For technical fields (e.g. product numbers, model codes), lemmatization can remain deactivated in order to preserve exact character strings.
The use of grammatical inflection (lemmatization) at search time is not recommended. In e-commerce, search queries typically consist of only 1–3 words and thus do not provide enough context for reliable lemmatization in the German language. This can distort user intent (e.g. "blau" is incorrectly turned into "blauen"), and the search delivers unpredictable or missing results. In practice, the relevant variants are already covered by the existing match strategies (including exact, prefix, N-gram, fuzzy, wildcard). If special cases must be represented, synonym mapping is the better alternative, since it is controllable and comprehensible. Lemmatization can still be useful at index time (e.g. for longer product texts with sufficient context) but should not be activated when processing the search query.
**Standard configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
lemmatization:
enabled: true
language: de
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | Activates (`true`) or deactivates (`false`) the grammatical reduction of search terms to their base form.
The basis are the language-specific word stems and models of the NLP libraries [*spaCy*](https://spacy.io/) and [Simplemma](https://adbar.github.io/simplemma/).
When deactivated, an exact-word search is performed without linguistic unification. |
| `language` | Defines the language for which the lemmatizer is applied. Currently available:
- German (`de`) = default
- English (`en`)
- Spanish (`es`)
- French (`fr`)
- Italian (`it`)
- Dutch (`nl`)
- Portuguese (`pt`)
- Danish (`da`)
- Czech (`cs`)
- Polish (`pl`)
- Finnish (`fi`)
- Indonesian (`id`)
- Slovak (`sk`)
- Turkish (`tr`)
- Swedish (`sv`)
- Norwegian Bokmål (`nb`)
Depending on the selected language, the corresponding language models from [*spaCy*](https://spacy.io/) and [Simplemma](https://adbar.github.io/simplemma/) are used to correctly recognize grammatical variants. |
### Index configuration (index\_configs)
`index_configs` controls per subshop which indexes are active at runtime during the search and how they behave. An index must be activated both in the [import module](#subshopkonfiguration-im-importmodul) and here in the search module to take effect.
**Basic structure**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
index_configs:
product: # Main index for product search
{...}
completion: # Index for autocompletion
{...}
category: # Index for category search
{...}
content: # Index for static content pages
{...}
```
#### Products (product index)
The product index is the main index and forms the basis of every product search. It is generally always active. The content configuration – i.e. which fields are searched, filtered, or displayed – is done via [fields\_config](#datenfelder). Via `index_configs.product`, it is primarily controlled whether the index is active at runtime.
**Example configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
index_configs:
product:
enabled: true
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates (`true`) or deactivates (`false`) the product index in the search module. Should generally remain set to `true`. Must also be activated in the [import module](#importmodul-der-suche) (`index_configs.product.enabled`). |
#### Autocompletion (completion index)
The completion index is used for the autocompletion of search terms. As with the product index, the configuration here is limited to the activation of the index – further settings (e.g. `Fuzziness`) are controlled via [suggest\_config](#suchvorschläge-suggest_config); the content basis is defined during import.
**Example configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
index_configs:
completion:
enabled: true
```
**Parameter description**
| **Parameter** | **Description** |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates (`true`) or deactivates (`false`) the completion index in the search module. Must also be activated in the [import module](#importmodul-der-suche) (`index_configs.completion.enabled`). |
#### Categories (category index)
If a category index was created during import, it can be activated in the search module per subshop. This means that in addition to products (and possibly content pages), categories are also taken into account in the search.
**Example configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
index_configs:
category:
enabled: true
custom_config:
search_fields:
- field: cat_str
boost: 2
- field: cat_str_path
boost: 1.5
display_fields:
- field: cat_id
- field: cat_id_path
- field: cat_str
- field: cat_str_path
search_config:
exact:
enabled: true
boost: 2.0
tie_breaker: 0.3
```
**Parameter description**
| **Parameter** | **Description** |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | Activates the search in the category index for the respective subshop. |
| `custom_config` | Configuration block for the category search. Defines which fields are searched and which are returned in the response. This key is analogously adopted for future additional indexes. |
| `search_fields` | List of fields that are searched during a category search. Should always contain at least `cat_str` and `cat_str_path`. A `boost` value can be specified per field. All subordinate keys are documented in [this section](#datenfelder-für-die-suche-search_fields). |
| `display_fields` | List of fields returned in the search response. At least `cat_id` is required. All subordinate keys are documented in [this section](#datenfelder-im-such-response-display_fields). |
| `search_config` | Optional configuration block for controlling the search types for the category index. Analogous to the [base configuration of the search module](#basiskonfiguration-des-suchmoduls-search_config), the individual search types (`exact`, `prefix`, `wildcard`, `ngram`, `fuzzy`) can be selectively activated, deactivated, and weighted. |
#### Content pages (content index)
If a **content index** was created during import, it can be activated in the search module per subshop. This means that in addition to products (and possibly categories), static content pages (e.g. "About us", terms and conditions, legal notice) are also taken into account in the search.
**Example configuration**
```yaml theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
...
content:
enabled: true
custom_config:
search_fields:
- field: title
- field: content
display_fields:
- field: source
- field: title
search_config:
exact:
enabled: true
boost: 2.0
tie_breaker: 0.3
...
```
**Parameter description**
| **Parameter** | **Description** |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | Activates the search in the content index for the respective subshop. |
| `custom_config` | Configuration block for the content-page search. |
| `search_fields` | List of fields used for the full-text search in the content index. For the content index, these fields are fixed (e.g. `title`, `content`). |
| `display_fields` | List of fields that must be included in the search response (e.g. `source` for reloading the content and `title` as label). Here too, the fields are fixed per index type. |
| `search_config` | Optional configuration block for controlling the search types for the content index. Analogous to the [base configuration of the search module](#basiskonfiguration-des-suchmoduls-search_config), the individual search types (`exact`, `prefix`, `wildcard`, `ngram`, `fuzzy`) can be selectively activated, deactivated, and weighted. |