Configuration of the search module

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 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.

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

database: *database
keydb: *keydb
indices: *indices
global_configs:
  search_config: {...}
  fields_config: {...}
  suggest_config: {...}
  filter_config: {...}
language_configs: {...}
subshop_configs: {...}

Import module

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

language_configs:
  de:
    lemmatization: {...}
    stopwords_filter: {...}
    fuzzy_filter: {...}
    punctuation_filter: {...}
  en:
    lemmatization: {...}
    stopwords_filter: {...}
    fuzzy_filter: {...}
    punctuation_filter: {...}

Import module

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

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

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

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 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

subshop_configs:
  deutsch:
    nlp_lang: de
    datafeed_url: http://content.<shop-id>.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 and 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).
`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.
`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. You can find more information about activating the function in the search module in the section stopwords_filter.
`synonyms`	Definition of manual synonym lists. More information in the section synonyms.
`lemmatization`	Configuration of grammatical inflections. You can find more information in the section lemmatization. You can find more information about activating the function in the search module in the section lemmatization.

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

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 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). 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.

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

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

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 and 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 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.

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

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: "<your-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, `<main>` 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.

Search suggestions (suggest_config)

Base configuration suggest_config

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, Content pages as well as the completion index).

Filter (filter_config)

Base configuration filter_config

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

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

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).
`prefix`	Configuration for prefix searches, in which the search term appears at the beginning of a word (see section Prefix Search).
`wildcard`	Configuration for wildcard searches, in which the search term can occur anywhere in the word (see section Wildcard Search).
`ngram`	Configuration for N-gram searches, in which parts of the search term match within a word (see section Ngram Search).
`fuzzy`	Configuration for error-tolerant (fuzzy) searches that also take slightly deviating spellings into account (see section Fuzzy Search).

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

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

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

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

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) Standard configuration

...
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

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).
`display_fields`	Specification of the fields that are passed to the frontend in the search result (see section Display Fields).
`filter_fields`	Definition of the available filters and their types in the search frontend (see section Filter Fields).
`sort_fields`	Specification of the fields by which the results can be sorted (see section Sort Fields).
`ngram_fields`	Definition of the fields for which the partial-word search (N-gram search) is active (see section Ngram Fields).
`variant_fields`	Definition of the fields that identify product variants (see section Variant Fields).
`category_field`	Specification of the field that contains the category IDs (see section 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

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). Standard configuration

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

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
`<datafeed_field_name>`	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.

Excluding certain products (filter_fields)

By default, all active products appear in the search. The exclusion of certain products is done within 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

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).

Data fields for the sorting (sort_fields)

This block is only configured if the UI component <ws-sort-box use-api="true"> 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. Standard configuration

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

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

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

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

...
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

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. Standard configuration stopwords_filter

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

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 and 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 and 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 and here in the search module to take effect. Basic structure

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. Via index_configs.product, it is primarily controlled whether the index is active at runtime. Example configuration

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 (`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; the content basis is defined during import. Example configuration

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 (`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

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.
`display_fields`	List of fields returned in the search response. At least `cat_id` is required. All subordinate keys are documented in this section.
`search_config`	Optional configuration block for controlling the search types for the category index. Analogous to the base configuration of the search module, 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

...
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, the individual search types (`exact`, `prefix`, `wildcard`, `ngram`, `fuzzy`) can be selectively activated, deactivated, and weighted.

Data feed setup Integration into the templates (storefront)

⌘I

​Import configuration & search module configuration

​Import module of the search

​Search module

​Data feed in the Dataflow Manager

​Configuration hierarchy (from v1.12.x / v1.11.x)

​Global configuration (global_configs)

​Language configuration (language_configs)

​Subshop configuration (subshop_configs)

​Configuration of the import module

​Data feed configuration

​Subshop configuration in the import module

​Tolerance for ignoring stopwords (stopwords)

​Synonyms (synonyms)

​Grammatical inflection (lemmatization)

​Categories

​Include content pages in the search index