Konfiguration des Such-Moduls - WEBSALE Dokumentation

Die Konfiguration des Suchmoduls ist derzeit noch nicht direkt im OSB verfügbar – weder über eine grafische Oberfläche noch über eine Code-basierte Eingabe. Aktuell kann die Einrichtung ausschließlich über WEBSALE vorgenommen werden. In Kürze wird die Möglichkeit zur Konfiguration per Code bereitgestellt. Wir bitten bis dahin noch um etwas Geduld und informieren Sie, sobald diese Option zur Verfügung steht. Bis dahin teilen Sie bitte Ihre gewünschten Einstellungen Ihrem WEBSALE-Ansprechpartner mit, damit die Anpassungen im Suchmodul für Sie vorgenommen werden können.

Importkonfiguration & Konfiguration des Suchmoduls

Damit das Suchmodul WEBSALE | search korrekt funktioniert, müssen sowohl das zugehörige Importmodul („Bereitstellen”) als auch das Suchmodul selbst konfiguriert werden. Beide Bereiche sind eng miteinander verknüpft, erfüllen jedoch unterschiedliche Aufgaben.

Importmodul der Suche

Im Importmodul werden die Daten für die Suche bereitgestellt. Hier wird definiert, welche Daten importiert und verfügbar gemacht werden – beispielsweise Produkt- und Kategoriedatenfelder, JSON-Dateien für Inhalte wie AGB, Kontakt oder FAQ, Stoppwörter und andere Suchparameter. Es reicht jedoch nicht aus, die Daten lediglich bereitzustellen. Im Suchmodul selbst muss zusätzlich konfiguriert werden, ob und wie diese Daten berücksichtigt werden sollen. Werden die bereitgestellten Daten im Suchmodul nicht aktiviert oder eingebunden, haben sie keinen Einfluss auf die Suchfunktion.

Suchmodul

Im Suchmodul wird festgelegt, wie die bereitgestellten Daten bei der Suche im Shop – also zur Laufzeit – berücksichtigt werden. Das bedeutet, dass beispielsweise importierte Stoppwörter, Filterregeln oder Datenfelder aktiv in der Such- und Filterlogik verwendet werden. Erst die Kombination aus bereitgestellten Daten (Importmodul) und deren Aktivierung im Suchmodul stellt sicher, dass die gewünschte Suchkonfiguration vollständig und wirksam ist.

Datenfeed im Dataflow Manager

Der Datenfeed bildet die Grundlage für das Importmodul. Der Datenfeed wird im Onlineservicebereich des DataflowManagers erstellt und enthält alle Produktinformationen, die im Suchindex berücksichtigt werden. Über den Datenfeed werden sämtliche Produktdaten bereitgestellt, die durchsucht, gefiltert oder sortiert werden sollen. Dazu müssen im Dataflow Manager alle relevanten Produktfelder enthalten sein – z. B. Name, Beschreibung, Kategorien, Preis, Lagerbestand, Attribute usw. Das Importmodul greift anschließend auf diesen Feed zu und wandelt die enthaltenen Daten in das interne JSON-Format für den Elasticsearch-Index um.

Konfigurationshierarchie (ab v1.12.x / v.1.11.x)

Die nachfolgend beschriebene Konfigurationshierarchie steht ab den Plugin-Versionen websale_search v.1.12.x und elasticsearch_manager v1.11.x zur Verfügung. Die Merge-Logik gilt für Suchmodul und Importmodul gleichermaßen.

Ab diesen Versionen unterstützen beide Module eine dreistufige Konfigurationshierarchie: global_configs → language_configs → subshop_configs. Dadurch können Einstellungen einmalig auf globaler Ebene definiert und bei Bedarf auf Subshop-Ebene gezielt überschrieben werden. So lassen sich Redundanzen in der Konfiguration vermeiden. Auf der obersten Ebene (Top-Level) werden grundsätzlich nur Infrastruktur-Aliase, beispielsweise für Datenbankverbindungen oder Index-Namen, definiert. Diese werden über YAML-Aliase (*/) in die untergeordneten Blöcke eingebunden.

Aktuell gibt es hiervon noch Ausnahmen. Im elasticsearch_manager wird datafeed weiterhin direkt auf Top-Level-Ebene konfiguriert. In websale_search gilt das gleiche für filter_config und suggest_config. Alle übrigen Einstellungen folgen dem dreifstufigen Modell über global_configs, language_configs und 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

Globale Konfiguration (`global_configs`)

global_configs bildet das unterste Level der Hierarchie. Hier definierte Werte gelten für alle Subshops, es sei denn, sie werden auf einer übergeordneten Ebene überschrieben. Suchmodul

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

Importmodul

database: *database
keydb: *keydb
indices: *indices
global_configs:
  variant_fields: {...}
  index_configs: {...}
language_configs: {...}
subshop_configs: {...}

Sprachkonfiguration (`language_configs`)

language_configs bildet das mittlere Level der Hierarchie. Hier können Konfigurationen für Sprachgruppen definiert werden, die für alle Subshops dieser Sprache gelten. Sie können nur durch explizite Subshop-Konfigurationen überschrieben werden. Suchmodul

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

Importmodul

language_configs:
  de:
    lemmatization: {...}
    stopwords: {...}
    synonyms: {...}
  en:
    lemmatization: {...}
    stopwords: {...}
    synonyms: {...}

Subshop-Konfiguration (`subshop_configs`)

subshop_configs bildet das höchste Level der Hierarchie. Hier kann jeder Konfigurationsparameter für einen einzelnen Subshop explizit überschrieben werden. Der Key language in den subshop_configs verknüpft den jeweiligen Subshop mit dem zu seiner Sprache zugehörigen language_configs-Block. Suchmodul

subshop_configs:
  deutsch:
    language: de  # lädt die Config "de" aus language_configs
    keyword_mappings: {...}
    wssearchdata_mappings: {...}
  englisch:
    language: en  # lädt die Config "en" aus language_configs
    keyword_mappings: {...}
    wssearchdata_mappings: {...}

Importmodul

subshop_configs:
  deutsch:
    language: de  # lädt die Config "de" aus language_configs
    datafeed_url: https://www.example-datafeed.de/example/download/path/file-deutsch.csv
  englisch:
    language: en  # lädt die Config "en" aus language_configs
    datafeed_url: https://www.example-datafeed.de/example/download/path/file-englisch.csv

Konfiguration des Importmoduls

Datenfeed-Konfiguration

Die Zuordnung und Verarbeitung des Feeds wird im Abschnitt datafeed der Konfiguration des Importmoduls festgelegt. Hier werden Format, Encoding, Speicherpfade und die Feldzuweisungen definiert, die der Suchindex beim Import benötigt. Standardkonfiguration

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

Parameterbeschreibung

Parameter	Beschreibung
`format`	Dateiformat des Datenfeeds, z.B. `csv`. Aktuell wird nur `csv` unterstützt.
`encoding`	Zeichencodierung des Feeds, z.B. `ISO-8859-1`. In der V8s werden aktuell nur ISO-Codierungen unterstützt, d.h. `utf-8` wird nicht unterstützt.
`chunk_size`	Anzahl der Zeilen pro Verarbeitungsschritt (Chunk). Standardwert: `1000`.
`dir_path`	Pfad für die automatisch generierten temporären JSON-Dateien, die beim Import als Zwischenspeicher dienen, z.B. `/data/subshop_data`. Pfad wird bei der Einrichtung des Suchmoduls durch WEBSALE angegeben und kann nicht geändert werden.
`remove_na_values`	Entfernt ungültige oder leere Werte aus dem Feed. - `true` → Leere oder ungültige Werte werden beim Import entfernt. - `false` → Werte bleiben erhalten und werden in Elasticsearch importiert.
`new_product_days`	Legt fest, wie viele Tage ein Produkt nach seiner Erstellung als „neu” gilt, z.B. `365`. Diese Information wird benötigt, um Sortierungen oder Filter nach “neusten Produkten” zu nutzen.
`invalid_docs_max`	Maximale Anzahl fehlerhafter Zeilen, bevor der Importprozess abgebrochen wird. Wert `0` bedeutet, dass der Prozess bei der ersten fehlerhaften Zeile stoppt. Damit der Prozess fortgeführt werden kann, müssen die Fehler behoben werden.
`log_percent`	Schwelle in Prozent, bei der der Fortschritt des Imports geloggt wird. Beispiel: `10` bedeutet, dass nach jeweils 10 % der verarbeiteten Daten ein Log-Eintrag erfolgt. Die Logs stehen zum aktuellen Zeitpunkt nur der WEBSALE AG zur Verfügung und können bei Bedarf resp. auf Anfrage zugesendet werden.
`product_id`	CSV-Spaltenname, der auf das Produktdatenfeld mit der eindeutigen Produktnummer zeigt. Es muss der technische Feldname des Produktdatenfelds, das die Produktnummer enthält, angegeben werden, z.B. `number`
`base_id`	Basis-Produkt-ID. Es muss der technische Feldname des Produktdatenfelds, das die Produktnummer enthält, angegeben werden, z.B. `prodiindex`
`is_base_product`	Es muss der technische Feldname des Produktdatenfelds aus dem Datenfeed angegeben werden, das die Information enthält, ob es sich um ein Basisprodukt handelt.
`creation_date`	Es muss der technische Feldname des Produktdatenfelds aus dem Datenfeed angegeben werden, das den Timestamp der Erstellung des Produktes enthält.
`api_store_id`	Name der Lagerbestands-ID aus der REST Lagerbestand Schnittstelle, z.B. `StoreId`
`es_store_id`	Lagerbestands-ID steht Es muss der technische Feldname des Produktdatenfelds aus dem Datenfeed angegeben werden, das diese Information enthält, z.B. `storeid`
`inventory`	Gibt den Lagerbestand eines Produktes an. Es muss der technische Feldname des Produktdatenfelds aus dem Datenfeed angegeben werden, das diese Information enthält, z.B. `inventory`
`inventory_active`	Gibt an, ob ein Produkt die Lagerbestandsverwaltung aktiviert hat. Es muss der technische Feldname des Produktdatenfelds aus dem Datenfeed angegeben werden, das diese Information enthält, z.B. `inventory-active`
`inventory_type`	Angabe, ob die Lagerbestandsverwaltung statisch oder dynamisch ist. Es muss der technische Feldname des Produktdatenfelds aus dem Datenfeed angegeben werden, das diese Information enthält, z.B. `inventory_type`
`category_str`	Enthält alle Kategorie-Strings (Kategorienamen) eines Produkts. Ist das Produkt nur einer Kategorie zugewiesen, ist es natürlich nur der eine Kategoriename. Bei mehrere Kategoriezuweisungen, können jedoch alle übergeben werden. Es muss der technische Feldname des Datenfelds aus dem Datenfeed angegeben werden, das diese Information enthält, z.B. `allcategories`
`category_ids`	Enthält die Kategorie-IDs des Produktes. Ist das Produkt nur einer Kategorie zugewiesen, ist es natürlich nur ein Index. Bei mehreren Kategoriezuweisungen, können jedoch alle Indexe übergeben werden. Es muss der technische Feldname des Datenfelds aus dem Datenfeed angegeben werden, das diese Information enthält, z.B. `allcatids`
`all_category_ids`	Enthält alle Kategorie-IDs des Produkts inklusive des Breadcrumbs, wenn ein Produkt mehreren Kategorien zugewiesen ist. Ist das Produkt nur einer Kategorie zugewiesen, ist es natürlich nur ein Index. Bei mehrere Kategoriezuweisungen, können jedoch alle Indexe übergeben werden. Es muss der technische Feldname des Datenfelds aus dem Datenfeed angegeben werden, das diese Information enthält, z.B. `catids`
`category_separator`	Liegen Produkte in mehrere Kategorien, muss hier das Trennzeichen, z.B. `/`, angegeben werden, um die Daten korrekt voneinander zu trennen.
`value_separator`	Für Werte innerhalb eines Feldes, z.B. Bredacrumb-Trenner für die Kategorie, kann man für jedes Feld verwenden, z. B. Inhaltsstoffe bei Nahrungsmitteln. Trennzeichen für mehrwertige Inhalte pro Feld. Beim Import werden die Werte des Feldes anhand dieses Separators in einzelne Einträge gesplittet (z. B. für Kategorie-Breadcrumbs oder Inhaltsstoffe). Das Trennzeichen muss mit der Feed-Erzeugung abgestimmt sein; es darf nicht ungekennzeichnet im eigentlichen Wert vorkommen (ggf. Escaping/Quoting im Feed sicherstellen).
`field_separator`	Zeichen, das die Spalten im CSV-Datenfeed voneinander trennt. Standard ist der Tabulator (TAB), empfohlen für Tab-CSV-Dateien. Andere Trennzeichen (z. B. `;` oder `,`) sind möglich, müssen aber mit der tatsächlichen Feed-Struktur übereinstimmen.
`index_category_hierarchy`	Legt fest, ob das Importmodul die Kategorie Hierarchie automatisch aufbaut. Bei `true` reicht es, wenn Produkte nur in der untersten Kategorie eingeordnet sind, sie werden dann auch in übergeordneten Kategorien gefunden. Bei `false` wird die Hierarchie nicht automatisch erstellt. Gilt global für alle Subshops. Default: `false`
`normalize_negative_prices`	(De-)aktiviert die Normalisierung negativer Preise. Wenn aktiviert, werden negative Preise auf 0.0 normalisiert.

Subshopkonfiguration im Importmodul

In diesem Abschnitt werden alle subshopspezifischen Einstellungen für das Importmodul definiert. Jeder Subshop wird dabei als eigener Konfigurationsblock unter dem Abschnitt subshop_configs angelegt. Über diese Konfiguration wird festgelegt, welche Daten je Subshop importiert und bereitgestellt werden. Dadurch kann das Suchmodul später pro Subshop gezielt auf die entsprechenden Daten zugreifen und die Suche individuell steuern. Standardkonfiguration für den Subshop Deutsch

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: {...}      # siehe Abschnitt „Toleranz für das Ignorieren von Stoppwörtern (stopwords)"
    synonyms: {...}       # siehe Abschnitt „Synonyme (synonyms)"
    lemmatization: {...}  # siehe Abschnitt „Grammatikalische Flexion (lemmatization)"
  englisch:
    {...}

Parameterbeschreibung

Parameter	Beschreibung
`nlp_lang`	Der Parameter `nlp_lang` legt fest, in welcher Sprache die textuelle Aufbereitung der Suchdaten erfolgt. Dabei werden sprachspezifische Modelle und Regeln aus den NLP-Bibliotheken spaCy und Simplemma verwendet. Diese sorgen dafür, dass die Suchdaten während des Imports sprachgerecht analysiert und verarbeitet werden – beispielsweise im Hinblick auf Wortstämme, Grundformen (Lemmata) und Stoppwörter. Aktuell verfügbare Sprachen: - Deutsch (`de`) = Standard - Englisch (`en`) - Spanisch (`es`) - Französisch (`fr`) - Italienisch (`it`) - Niederländisch (`nl`) - Portugiesisch (`pt`) - Dänisch (`da`) - Tschechisch (`cs`) - Polnisch (`pl`) - Finnisch (`fi`) - Indonesisch (`id`) - Slowakisch (`sk`) - Türkisch (`tr`) - Schwedisch (`sv`) - Norwegisch Bokmål (`nb`)
`datafeed_url`	URL des Datenfeeds. Wird vom WEBSALE Support eingerichtet und bereitgestellt.
`variant_fields`	Liste der technischen Produktdatenfelder, z.B. Farbe (`color`), Größe (`size`) etc., die Varianten eines Produktes beschreiben (siehe Abschnitt Variant Fields).
`enabled`	Verknüpft beim Import Basis-Produkte und ihre Varianten.
`fields`	Technische Namen der Variantenfelder eines Produkts (immer in Kleinbuchstaben)
`index_configs`	Indexspezifische Konfigurationen
`product`	Hauptindex für die Produktsuche. Enthält die Produktdatenfelder für den Suchindex.
`enabled`	Aktiviert die Erstellung dieses Index im Import
`custom_fields`	Individuell definierte Produktdatenfelder, die zusätzlich in den Suchindex aufgenommen werden. Angabe des technischen Namen des Produktdatenfeldes.
`name`	Technischer Name des Produktdatenfeldes (immer in Kleinbuchstaben)
`type`	Datentyp des Feldes. Verfügbare Typen: `text`, `keyword`, `integer`, `float`, `double`, `date`, `boolean`, `template`. `template` ist ein spezieller Feldtyp für Textfelder, die sowohl durchsuchbar als auch filterbar sein sollen.
`category`	Index für die Kategoriesuche. Ermöglicht es, Kategorien als eigenständigen Index zu durchsuchen. Wenn beim Import ein Kategorie-Index angelegt wurde, kann dieser in der Konfiguration des Suchmoduls aktiviert werden.
`enabled`	Aktiviert die Erstellung bzw. Nutzung dieses Index. Muss sowohl in der Import-Konfiguration als auch in der Suchmodul-Konfiguration auf `true` gesetzt werden.
`custom_fields`	Individuell definierte Felder, die zusätzlich in den Kategorie-Index aufgenommen werden sollen, analog zu `product` (siehe Abschnitt custom_fields des Produktindex). Im Default sind nur die Standard-Kategoriefelder enthalten (IDs und Name). Jedes Feld wird mit `name` (technischer Feldname, immer Kleinbuchstaben) und `type` (Datentyp, z.B. `text`, `keyword`, `template`) angegeben.
`custom_config`	Konfigurationsblock für die Kategoriesuche. Hier wird festgelegt, welche Felder durchsucht und welche in der Antwort zurückgegeben werden. Dieser Key wird für zukünftige zusätzliche Indizes analog übernommen.
`search_fields`	Liste der Felder, die bei einer Kategoriensuche durchsucht werden (analog zu `product`). Sollte immer mindestens die Felder `cat_str` und `cat_str_path` enthalten. Pro Feld kann ein `boost`-Wert angegeben werden, um die Gewichtung zu steuern.
`field`	Technischer Name des zu durchsuchenden Feldes. Per Default verfügbar: `cat_str`, `cat_str_path`.
`boost`	Gewichtungsfaktor für das Feld bei der Suche. Höhere Werte erhöhen die Relevanz von Treffern in diesem Feld.
`display_fields`	Liste der Felder, die in der Suchantwort zurückgegeben werden (analog zu `product`). Benötigt wird mindestens `cat_id`. Per Default verfügbare Felder: `cat_id`, `cat_id_path`, `cat_str`, `cat_str_path`.
`field`	Technischer Name des Feldes, das in der Antwort enthalten sein soll.
`content`	Hauptindex für die Suche über Inhaltsseiten wie Impressum, Datenschutz, AGB etc. Mehr Informationen dazu finden Sie im Abschnitt content.
`completion`	Index für Vorschläge (Autocomplete resp. Autovervollständigung)
`enabled`	Aktiviert die Erstellung dieses Index im Import
`fields`	Liste der Produktdatenfelder aus dem Suchindex, die für Vorschläge verwendet werden.
`stopwords`	Definition der Stoppwort-Liste. Mehr Informationen dazu finden Sie im Abschnitt stopwords. Mehr Informationen zur Aktivierung der Funktion im Suchmodul finden Sie im Abschnitt stopwords_filter.
`synonyms`	Definition manueller Synonymlisten. Mehr Informationen dazu im Abschnitt synonyms.
`lemmatization`	Konfiguration der grammatikalischen Flexionen. Mehr Informationen dazu finden Sie im Abschnitt lemmatization. Mehr Informationen zur Aktivierung der Funktion im Suchmodul finden Sie im Abschnitt lemmatization.

Toleranz für das Ignorieren von Stoppwörtern (stopwords)

Stoppwörter sind wenig aussagekräftige Wörter (z.B. Artikel, einfache Präpositionen), die bei der Auswertung von Suchanfragen ignoriert werden können, um irrelevante Übereinstimmungen zu reduzieren. Ob diese Ignorierlogik zur Laufzeit angewendet wird, steuert das Suchmodul. Welche Wörter als Stoppwörter behandelt, ausgenommen (Whitelist) oder zusätzlich aufgenommen (Blacklist) werden, definiert das Import-Modul. In diesem Abschnitt wird festgelegt, wie die Suchfunktion mit häufig vorkommenden, bedeutungsarmen Wörtern („Stoppwörtern”) umgeht. Als Grundlage dient die Standardliste von spaCy, die gängige Funktionswörter wie der, die, das, mit, von usw. enthält. Für optionale Whitelist- und Blacklist-Einträge kann diese Liste individuell angepasst werden:

Die Whitelist entfernt Wörter aus der spaCy-Stoppwortliste, sodass sie nicht ignoriert und bei der Suche berücksichtigt werden.
Die Blacklist fügt Wörter zur spaCy-Liste hinzu, sodass sie bei der Suche ausgefiltert werden. (Wird ein Wort blackgelistet, das bereits enthalten ist, bleibt die Wirkung unverändert.)

Optional kann eine eigene .txt-Datei mit Stoppwörtern verwendet werden. Soll diese extern – z. B. auf einem Kundensystem – hinterlegt werden, ist eine technische Abstimmung zur Einbindung der Datei erforderlich. Damit die konfigurierten Stoppwörter im Suchprozess tatsächlich berücksichtigt werden, muss im Suchmodul der Parameter stopwords_filter.enabled: true aktiviert sein → siehe Abschnitt „Stoppwort-Filter im Suchmodul”. Standardkonfiguration stopwords

stopwords:
  path: ""        # optional: Pfad zu eigener .txt, sonst spacy-Default
  whitelist:      # Begriffe, die NICHT als Stopwort behandelt werden sollen
    - mit         # wichtig für Produktausprägungen (z. B. Jacke mit Kapuze)
    - ohne        # wichtig für Tiernahrung (z. B. ohne Getreide)
    - für         # wichtig für Zielgruppen (z. B. für Damen)
    - in          # wichtig für Farben/Größen (z. B. in Blau, in 40)
    - und         # wichtig für Kombinationen (z. B. Huhn und Reis)
  blacklist:      # zusätzliche Stopwörter, die entfernt werden sollen
    - der
    - die
    - das
    - ein
    - eine
    - einer
    - eines
    - einem
    - einen
    - bei
    - nach
    - von
    - zu
    - zum
    - zur
    - auch
    - oder

Parameterbeschreibung stopwords

Parameter	Beschreibung
`path`	Pfad zu einer eigenen `.txt`-Datei mit Stoppwörtern (ein Wort pro Zeile). Beispiel: `/data/stopwords_de.txt` Wird keine Datei angegeben, wird die Standardliste von spaCy verwendet.
`whitelist`	Wörter, die nicht als Stoppwort behandelt werden sollen (Ausnahmen von der Standardliste). Eignet sich für fachlich relevante Begriffe wie „mit”, „ohne”, „für”, „in”, „und”.
`blacklist`	Zusätzliche Wörter, die als Stoppwort entfernt werden sollen (Ergänzung zur Standardliste von spaCy) Typisch: Artikel/Präpositionen wie „der”, „die”, „das”, „ein”, „eine”, „einer”, „eines”, „einem”, „einen”, „bei”, „nach”, „von”, „zu”, „zum”, „zur”, „auch”, „oder”.

Die Funktion muss zusätzlich dann noch für das Suchmodul aktiviert werden.

Synonyme (synonyms)

Die Synonymfunktion ermöglicht es, Begriffe in der Suche miteinander zu verknüpfen. Dadurch erscheinen bei der Eingabe eines Begriffs auch Treffer zu gleichbedeutenden oder verwandten Begriffen. Synonyme können entweder bidirektional („Jacke” = „Jacket”) oder unidirektional („Turniersakko” → „Turnierjacke”) definiert werden. Optional lassen sich Synonymlisten als Datei hinterlegen oder direkt in der Konfiguration pflegen. Im Standard sind keine Synonyme hinterlegt. Die Funktion wird aktiv, sobald entweder eine Synonymliste (path) angegeben oder manuelle Synonyme (clouds) definiert werden. Beispielkonfiguration

synonyms:
    path: ""
    clouds:
      - src: # Beispiel 1
        - trenchcoat
        - kutte
        - caban
        - janker
        target:
          - mantel
          - jacke
        mode: bi
      - src: # Beispiel 2
          - kängoro
          - kängguhru
          - kengooroo
        target: känguru
        mode: uni

Beispiel 1 (mode: bi) Die Begriffe „trenchcoat”, „kutte”, „caban”, „janker”, „mantel” und „jacke” sind bidirektional miteinander verknüpft. Eine Suche nach einem dieser Begriffe führt auch zu Treffern, die einen der anderen Begriffe enthalten. Beispielsweise liefert eine Suche nach „Janker” auch Ergebnisse mit „Mantel” oder „Trenchcoat”, und umgekehrt.
Beispiel 2 (mode: uni) Die Begriffe „kängoro”, „kängguhru” und „kengooroo” werden einseitig auf den Begriff „känguru” gemappt. Eine Suche nach einer der Schreibvarianten führt zu Treffern mit „känguru”, nicht jedoch umgekehrt. Dieser Modus eignet sich vor allem für Tippfehler, Schreibvarianten oder vereinheitlichte Begriffe.

Parameterbeschreibung

Parameter	Beschreibung
`path`	Optional kann eine TXT-Datei mit Synonymen hinterlegt werden (ein Wort pro Zeile). Beim Parameter wird der Pfad der `txt`-Datei angegeben. Beispiel: `/data/stopwords_de.txt` Änderungen an der Datei erfordern eine Neuindexierung. Falls die Datei extern – z. B. auf einem Server des Kunden – hinterlegt werden soll, ist eine gesonderte technische Abstimmung erforderlich, um den Zugriff auf diese Datei sicherzustellen.
`clouds`	Liste mit manuell definierten Synonymgruppen. Jede Gruppe beschreibt eine Beziehung zwischen Quell- und Zielbegriffen.
`src`	Quellbegriff(e), die ersetzt oder verknüpft werden sollen. Kann als einzelner String oder als Liste angegeben werden.
`target`	Zielbegriff(e), auf die verwiesen wird. Dies kann als einzelner String oder als Liste angegeben werden.
`mode`	Verknüpfungsmodus: - `uni` → unidirektional (nur `src → target`, d. h. bei Eingabe von `src` wird nach `target` gesucht, nicht umgekehrt) - `bi` → bidirektional (alle Begriffe innerhalb von `src` und `target` gelten gegenseitig als Synonyme)

Hinweis: Nach Änderungen an Synonymen muss die Datenfeed-Generierung manuell gestartet werden, damit eine Neuindexierung erfolgt.

Grammatikalische Flexion (lemmatization)

In diesem Abschnitt wird festgelegt, ob und für welche Felder grammatikalische Wortformen beim Import auf ihre Grundform reduziert werden. Dadurch erkennt die Suche auch sprachliche Varianten – etwa, dass „rote Hemden”, „rotes Hemd” oder „Hemd in Rot” denselben Begriff meinen. Die Funktion verbessert die sprachliche Erkennung und sorgt für natürlichere Suchergebnisse. Sie sollte für beschreibende Textfelder (z. B. name, descr) aktiviert, für technische Felder (z. B. product_id, sku) jedoch deaktiviert werden. Standardkonfiguration

lemmatization:
  enabled: true
  language: de
  fields:
    - name
    - descr

Die grammatikalische Grundform-Erkennung ist aktiviert (enabled: true).
Es wird die deutsche Sprachlogik verwendet (language: de).
Die Felder name und descr werden beim Import auf ihre Grundformen reduziert.
Dadurch erkennt die Suche auch grammatikalisch oder wortstellerisch variierende Begriffe (z. B. „rotes Hemd” ↔ „Hemd in Rot”).

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) die grammatikalische Reduktion von Suchbegriffen auf ihre Grundform. Grundlage sind die sprachspezifischen Wortstämme und Modelle der NLP-Bibliotheken spaCy und Simplemma. Bei deaktivierter Einstellung erfolgt eine wortgenaue Suche ohne sprachliche Vereinheitlichung.
`language`	Definiert die Sprache, für die der Lemmatizer angewendet wird. Aktuell verfügbar: - Deutsch (`de`) = Standard - Englisch (`en`) - Spanisch (`es`) - Französisch (`fr`) - Italienisch (`it`) - Niederländisch (`nl`) - Portugiesisch (`pt`) - Dänisch (`da`) - Tschechisch (`cs`) - Polnisch (`pl`) - Finnisch (`fi`) - Indonesisch (`id`) - Slowakisch (`sk`) - Türkisch (`tr`) - Schwedisch (`sv`) - Norwegisch Bokmål (`nb`) Je nach gewählter Sprache werden die entsprechenden Sprachmodelle von spaCy genutzt, um grammatikalische Varianten korrekt zu erkennen.
`fields`	Legt fest, welche Datenfelder aus dem Import sprachlich analysiert und lemmatisiert werden. Es müssen die technischen Feldnamen des Datenfeeds angegeben werden. Standardmäßig sind `name` (Produktname) und `descr` (Produktbeschreibung) hinterlegt. Änderungen an dieser Einstellung erfordern einen erneuten Import.

Die Funktion muss zusätzlich dann noch für das Suchmodul aktiviert werden.

Kategorien

Feste Felder im Category-Index

Feld	Beschreibung
`cat_id`	Kategorie-ID.
`cat_str`	Kategorie-Name.
`cat_id_path`	Kategorie-ID-Pfad.
`cat_str_path`	Vollständiger Kategorie-Pfad als String.
`cat_image`	Kategorie-Bild (optional).
`sort_field`	Wird automatisch von `cat_str_path` befüllt (kann via `custom_fields` überschrieben werden).

Inhaltsseiten in den Suchindex aufnehmen

Neben Produkten (und ggf. Kategorien) können auch statische Inhaltsseiten in die Suche einbezogen werden – z. B. „Über uns”, AGB, Impressum oder Datenschutzerklärung. Dafür wird im Importmodul der Content-Import aktiviert (content.enabled) und die Anbindung an die jeweilige Shop-API (VX oder v8) konfiguriert. Optional lassen sich die zu indexierenden Seiten gezielt einschränken (z. B. über included_content).

Category und Content sind spezielle Indizes, die, anders als der Produktindex, nicht frei um neue Felder erweitert werden können. Beide arbeiten mit einem festen Satz an Feldern (siehe unten). Der Parameter custom_fields dient hier ausschließlich dazu, das Elasticsearch-Mapping bestehender Felder zu überschreiben oder anzupassen (z.B. Analyzer, Feldtyp). Er wurde vom Produktindex analog für andere Indizes übernommen, erweitert aber nicht die Indexierung um neue Datenfelder.

Feste Felder im Content-Index

Feld	Beschreibung
`source`	Pfad zur Content-Seite (z.B. `content/gtc.htm`).
`title`	Seitentitel .
`content`	Extrahierter Text-Inhalt der Seite.
`sort_field`	Wird automatisch von `title` befüllt (kann über `custom_fields` überschrieben werden).

Standardkonfiguration des Demoshops

content:
  enabled: true
  custom_fields: # analog zu product/category, im Default sind nur 'title' und 'content' enthalten
    - name: field_name
      type: field_type
  custom_config:
    host: demo.shop.websale.biz
    user: "example@websale.de"
    password: "<ihr-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"
    # folgende Keys sind für VX nicht relevant
    api_version: v8
    base_path: /api/
    auth_url: /authent/login/
    shop_url: www.myshop.de

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert den Import und das Indexieren von statischen Inhaltsseiten für die Suche.
`custom_fields`	Optionale Anpassung des Elasticsearch-Mappings für den Content-Index (analog zu `Product`/`Category`). Damit lassen sich bestehende Felder im Mapping überschreiben oder erweitern. Verändert nur das Mapping! Die Indexierung von `Content` und `Category` ist fest definiert und lässt sich nicht über die Konfiguration um neue Datenfelder erweitern.
`custom_config`	Technische Zusatzkonfiguration für das Importieren und Auslesen der statischen Inhalte (unterscheidet sich zwischen VX und v8).
`host`	Host der API. - V8s: Host der v8-API (z. B. `websale.de`) - Neue Version: entspricht der Shop-ID-Domain (z. B. `common-id.shop.websale.net`).
`user`	Benutzername für die Authentifizierung an der Auth-API.
`password`	Passwort für die Authentifizierung an der Auth-API.
`endpoint`	API-Endpunkt, von dem die SEO-Template-/URL-Daten geladen werden. - V8s:`seo/templates`. - Neue Version:`seo/urls/templates`
`params`	Optionale URL-Parameter für den API-Call. Nur für die neue Version. - `size` - Maximale Response-Größe (max. 300 SEO-URLs pro Request) - `sort` - Sortierung der Response-Items (z. B. `resourceIdentifier:asc`)
`osbcommonid`	Nur für V8s. Common-ID für OSB (sofern für die jeweilige Umgebung erforderlich).
`path_field`	Feldname aus der API-Response, das den Pfad der Seite enthält (z. B. `/ueber-uns`). - V8s:`terms` - Neue Version:`path`
`source_field`	Feldname aus der API-Response, das die Quelle/Template-Referenz enthält (z. B. `content/aboutUs.htm`). - V8s:`template` - Neue Version:`resourceIdentifier`
`content_id`	Optionale ID eines HTML-Containers, aus dem der relevante Seiteninhalt extrahiert wird (z. B. `wsMainContent`). Wenn nicht gesetzt, wird standardmäßig `<main>` ausgelesen; falls nicht vorhanden, wird die komplette Seite (inkl. Header/Footer) übernommen.
`included_content`	Optionale Positivliste: importiert/indexiert nur die hier angegebenen „source”-Einträge (z. B. einzelne Templates/Content-Dateien). Ohne Angabe werden alle verfügbaren Seiten berücksichtigt.
`api_version`	Nur V8s. Version der Shop-API (z.B. `v8`). In der neuen Version entfällt dieser Parameter, da ein passender Default-Wert hinterlegt ist.
`base_path`	Nur V8s. Basispfad für Schnittstellen (z.B. `/api/`). In der neuen Version entfällt dieser Parameter, da ein passender Default-Wert hinterlegt ist.
`auth_url`	Nur V8s. Endpunkt der Auth-API (z. B. `/authent/login/` bzw. mit Common-ID). In der neuen Version entfällt dieser Parameter, da ein passender Default-Wert hinterlegt ist.
`shop_url`	Nur V8s. Öffentliche Shop-URL. In der neuen Version entspricht `host` in der Regel der Shop-URL bzw. ist dafür ausreichend.

Konfiguration des Suchmoduls

Suchvorschläge (suggest_config)

Basiskonfiguration 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

Parameterbeschreibung

Parameter	Beschreibung
`query`	Konfiguration für textbasierte Suchvorschläge (Autovervollständigung der Sucheingabe).
`product`	Konfiguration für Produkt-Vorschläge. Grundlage bildet der Produkt-Index (siehe Import-Konfiguration).
`category`	Konfiguration für Kategorie-Vorschläge. Grundlage bildet der Kategorie-Index (siehe Import-Konfiguration).
`content`	Konfiguration für Inhaltsseiten-Vorschläge. Grundlage bildet der Content-Index (siehe Import-Konfiguration).
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) den jeweiligen Suggest-Typ. Deaktivierte Typen werden im Frontend nicht angezeigt, auch wenn die entsprechenden HTML-Komponenten vorhanden sind.
`size`	Anzahl der Suchvorschläge für den jeweiligen Suggest-Typ.
`fuzziness`	Steuert die fehlertolerante Suchmethode (nur für Typ `query`), die Tippfehler oder Abweichungen in der Schreibweise innerhalb der Suggest ausgleicht. Es kann die erlaubte Edit-Distanz innerhalb der Suggest (Ersetzen, Einfügen, Löschen) pro Wort konfiguriert werden: - `0` → keine Fehlertoleranz (es muss exakt passen, nach Analyse/Normalisierung) - `1` → bis zu 1 Edit erlaubt - `2` → bis zu 2 Edits erlaubt - `AUTO` → passt die Distanz an die Wortlänge an: Wortlänge 1 - 2 → 0, 3 - 5 → 1, ≥6 → 2 (bei 1 - 2 Zeichen keine Toleranz, bei 3 - 5 genau 1 Edit, ab 6 bis zu 2 Edits) - `AUTO:x,y` → eigene Schwellen: bis x-1 Zeichen → 0, ab x bis y-1 → 1, ab y → 2. Beispiel `AUTO:4,8`: Längen ≤4 → 0, 5 - 8 → 1, ≥9 → 2

Grundlage der Suggest-Typen product, category und content bilden die jeweiligen Indizes. Diese müssen zunächst im Importmodul aktiviert und konfiguriert sein, damit die entsprechenden Vorschläge zur Laufzeit verfügbar sind (siehe Kategorien, Inhaltsseiten sowie den Completion-Index).

Filter (filter_config)

Basiskonfiguration filter_config

filter_config:
  filter_size: 100
  doc_count: 1
  default_min: 0
  default_max: 1000

Parameterbeschreibung

Parameter	Beschreibung
`filter_size`	Anzahl der Filteroptionen pro Filter
`doc_count`	Mindestanzahl der Dokumente, in denen ein Wert vorkommen muss, um als Filteroption zur Auswahl zu stehen
`default_min`	Fallback für Range-Filter, Minimalwert
`default_max`	Fallback für Range-Filter, Maximalwert

Subshopkonfiguration für das Suchmodul

Die Konfiguration des Suchmoduls ist pro Subshop definiert und wird jeweils unter der Subshop-ID als Schlüssel abgelegt. Übersichtsbeispiel

subshop_configs:
  {subshop_id}:          # z. B. 01-aa: oder 83-it: (lowercase)
    search_config:       # Basiskonfiguration der Sucharten (exakt, Präfix, Fuzzy …)
      {...}
    fields_config:       # Felddefinitionen und Gewichtungen
      {...}
    index_configs:       # Indexeinstellungen
      {...}
    punctuation_filter:  # Behandlung von Sonderzeichen
      {...}
    fuzzy_filter:        # Schwellenwerte für unscharfe Suche
      {...}
    stopwords_filter:    # Zu ignorierende Wörter
      {...}
    lemmatization:       # Wortgrundformreduktion
      {...}

Basiskonfiguration des Suchmoduls (search_config)

Die Basiskonfiguration definiert, welche Sucharten aktiv sind und wie Suchbegriffe ausgewertet werden. Über diese Einstellungen wird gesteuert, ob Suchbegriffe exakt, teilweise, unscharf oder als Wortbestandteile gefunden werden sollen. Jede Suchart kann separat aktiviert, gewichtet und kombiniert werden. Grundstruktur

search_config:
  mode: add
  exact:
    {...}
  prefix:
    {...}
  wildcard:
    {...}
  ngram:
    {...}
  fuzzy:
    {...}

Parameterbeschreibung

Parameter	Beschreibung
`mode`	Legt fest, wie die Feldboosts der einzelnen Sucharten verrechnet werden (additiv oder multiplikativ).
`exact`	Konfiguration für exakte Übereinstimmungen von Suchbegriffen (siehe Abschnitt Exact Search).
`prefix`	Konfiguration für Präfix-Suchen, bei denen der Suchbegriff am Wortanfang steht (siehe Abschnitt Prefix Search).
`wildcard`	Konfiguration für Wildcard-Suchen, bei denen der Suchbegriff an beliebiger Stelle im Wort vorkommen kann (siehe Abschnitt Wildcard Search).
`ngram`	Konfiguration für N-Gram-Suchen, bei denen Teile des Suchbegriffs innerhalb eines Wortes übereinstimmen (siehe Abschnitt Ngram Search).
`fuzzy`	Konfiguration für fehlertolerante (unscharfe) Suchen, die auch leicht abweichende Schreibweisen berücksichtigen (siehe Abschnitt Fuzzy Search).

Exakte Suche (exact)

Die exakte Suche liefert Treffer nur dann, wenn der Suchbegriff exakt mit dem gespeicherten Wort übereinstimmt. Sie bildet damit die präziseste Form der Suche und wird meist als Basis oder Ergänzung zu anderen Sucharten verwendet. Treffer aus der exakten Suche erhalten in der Regel eine höhere Relevanz, da sie eine vollständige Übereinstimmung darstellen. Diese Suchart sollte immer aktiviert bleiben, da sie sicherstellt, dass bei identischen Schreibweisen (z. B. exakte Produktnamen, Marken, Artikelnummern) die relevantesten Ergebnisse zuerst erscheinen. Über den Boost-Wert lässt sich die Gewichtung gegenüber anderen Sucharten feinjustieren. Standardkonfiguration

exact:
    enabled: true
    boost: 2.0
    tie_breaker: 0.3

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) die exakte Suche. Sollte in der Regel aktiviert bleiben.
`boost`	Relevanzfaktor für exakte Treffer. Ein höherer Wert verstärkt die Gewichtung exakter Übereinstimmungen im Gesamtranking (empfohlen: 2.0 – 3.0).
`tie_breaker`	Bestimmt, wie stark sich Mehrfachtreffer desselben Suchbegriffs in mehreren Feldern auf den Score auswirken. Ein Wert von 0.1 – 0.3 ist in der Regel sinnvoll, um die Relevanz leicht zu erhöhen, ohne sie zu dominieren.

Präfix-Suche (prefix)

Die Präfix-Suche liefert Treffer, wenn der Suchbegriff am Anfang eines Wortes steht. Sie wird typischerweise genutzt, um Treffer während der Eingabe zu ermöglichen oder um Wortanfänge zu erkennen - zum Beispiel liefert die Eingabe „schn” auch Ergebnisse wie Schneider, Schnürsenkel oder Schnalle. Diese Suchart ergänzt die exakte Suche sinnvoll, da sie flexibler auf Teilbegriffe reagiert, ohne die Präzision vollständig aufzugeben. Besonders nützlich ist sie in Kombination mit Autocomplete-Funktionen und Suggest-Komponenten. Standardkonfiguration

prefix:
    enabled: true
    boost: 1.75

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) die Präfix-Suche.
`boost`	Relevanzfaktor für Präfix-Treffer. Empfohlener Bereich: 1.0 – 2.0, um Wortanfänge leicht zu bevorzugen, ohne exakte Treffer zu verdrängen.

Wildcard-Suche (wildcard)

Die Wildcard-Suche findet Treffer, wenn der Suchbegriff an beliebiger Stelle innerhalb eines Wortes vorkommt. Sie ist deutlich flexibler als die Präfix-Suche, da sie auch Wortbestandteile erkennt - zum Beispiel liefert die Eingabe „hose” Treffer wie Jeanshose, Arbeitshose oder Strumpfhose. Diese Suchart eignet sich besonders für Fälle, in denen Nutzer nicht den exakten Wortanfang kennen, z. B. bei zusammengesetzten Begriffen, Varianten von Produktnamen oder technischen Bezeichnungen. Standardkonfiguration

wildcard:
    enabled: true
    boost: 1.5

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) die Wildcard-Suche. Empfohlen, wenn Teilbegriffe oder Wortbestandteile relevant sind.
`boost`	Relevanzfaktor für Wildcard-Treffer. Empfohlener Bereich: 0.5 – 1.5, um flexible Treffer zuzulassen, aber exakte Übereinstimmungen weiterhin zu priorisieren.

Teilwortsuche / N-Gram-Suche (ngram)

Die N-Gram-Suche ermöglicht Treffer, wenn ein Teil des Suchbegriffs innerhalb eines Wortes vorkommt - unabhängig davon, ob der Begriff am Anfang, in der Mitte oder am Ende steht. Sie basiert auf der Aufteilung von Wörtern in kleine Einheiten (sogenannte N-Gramme), die während des Indexaufbaus erzeugt werden. Diese Suchart eignet sich besonders für technische Begriffe, Modellnummern, Artikelcodes oder zusammengesetzte Wörter, bei denen der Nutzer häufig nur Teile des Begriffs kennt. Beispiel: Die Eingabe „AB12” findet auch AB1234-X oder XX-AB12-Z. Standardkonfiguration

ngram:
    enabled: true
    boost: 1.25
    tie_breaker: 0.3
    minimum_should_match: 80%

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) die N-Gram-Suche.
`boost`	Relevanzfaktor für Teilworttreffer. Empfohlener Bereich: 0.8 – 1.5, um ergänzende Treffer zuzulassen, ohne exakte Ergebnisse zu verdrängen.
`tie_breaker`	Bestimmt, wie stark Mehrfachtreffer in verschiedenen Feldern den Gesamtscore beeinflussen. Werte zwischen 0.1 – 0.3 sind in der Regel sinnvoll.
`minimum_should_match`	Über den Parameter kann gesteuert werden, wie viel Prozent der N-Gramme übereinstimmen müssen, um als Treffer zu zählen – das verbessert die Ergebnisqualität. Empfohlen: 60 – 80 % für eine gute Balance zwischen Trefferquote und Präzision.

Fehlertolerante Suche & Levenshtein-Distanz (fuzzy)

Die Fuzzy-Suche ist eine fehlertolerante Suchmethode, die Tippfehler oder Abweichungen in der Schreibweise ausgleicht. Grundlage ist die Levenshtein-Distanz, die zählt, wie viele Bearbeitungsschritte (Einfügen, Löschen, Ersetzen) zwei Wörter voneinander trennen. Beispiele:

„Haus” → „Maus” = Distanz 1 (1 Buchstabe ersetzt)
„Haus” → „Huas” = Distanz 2 (Buchstaben vertauscht → Ersetzen + Ersetzen)
„Haus” → „Hause” = Distanz 1 (ein Buchstabe eingefügt)

fuzzy steuert die globale fehlertolerante Suche auf Basis der Levenshtein-Distanz. Hier wird festgelegt, ob Fuzzy aktiv ist, welche Fehlertoleranz (z. B. AUTO abhängig von der Wortlänge) gilt und wie stark fuzzy Treffer im Scoring gewichtet werden (boost, tie_breaker). Die Konfiguration wirkt grundsätzlich auf alle Suchbegriffe und Felder, sofern sie nicht durch nachgelagerte Regeln eingeschränkt wird → siehe Ausnahmen zur globalen Fuzzy-Logik (fuzzy_filter) Standardkonfiguration

...
fuzzy:
  enabled: true
  boost: 0.75
  tie_breaker: 0.3
  fuzziness: AUTO
...

Fuzzy-Suche aktiviert: Fehlertolerante Matches (auf Basis der Levenshtein-Distanz) sind aktiv.
Gewichtung: Mit boost = 0.75 erhalten fuzzy-Treffer rund 75 % des Gewichts eines exakten Treffers; höhere Werte priorisieren fuzzy stärker, 0 deaktiviert den Boost-Effekt.
Feldübergreifende Gewichtung: tie_breaker = 0.3 bewirkt, dass zusätzliche Treffer in weiteren Feldern den Score mit ca. 30 % beitragen; kleinere Werte dämpfen, größere Werte verstärken diesen Mehrfeld-Effekt.
Fehlertoleranz: fuzziness = AUTO passt die erlaubte Edit-Distanz an die Wortlänge an (1 - 2 Zeichen → 0, 3 - 5 → 1, ≥6 → 2).

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert oder deaktiviert die fehlertolerante Suche. Bei `false` findet keine Fuzzy-Auswertung statt; Einstellungen wie `fuzziness`, `boost` oder `tie_breaker` greifen dann nicht.
`boost`	Gewichtet den Einfluss der Fuzzy-Treffer im Ranking. - `1.0` entspricht neutral (weder Ab- noch Aufwertung) - Werte `< 1.0` schwächen Fuzzy gegenüber exakten Treffern ab (z. B. `0.75`) - Werte `> 1.0` stärken Fuzzy (z. B. `1.5`) - `0` bedeutet: Fuzzy-Treffer beeinflussen das Scoring nicht (die Abfrage kann weiterhin matchen, liefert aber keinen Score-Beitrag).
`fuzziness`	Steuert die erlaubte Edit-Distanz (Ersetzen, Einfügen, Löschen) pro Wort. - `0` → keine Fehlertoleranz (es muss exakt passen, nach Analyse/Normalisierung) - `1` → bis zu 1 Edit erlaubt - `2` → bis zu 2 Edits erlaubt - `AUTO` → passt die Distanz an die Wortlänge an: Wortlänge 1 - 2 → 0, 3 - 5 → 1, ≥6 → 2 (bei 1 - 2 Zeichen keine Toleranz, bei 3 - 5 genau 1 Edit, ab 6 bis zu 2 Edits) - `AUTO:x,y` → eigene Schwellen: bis x-1 Zeichen → 0, ab x bis y-1 → 1, ab y → 2. Beispiel `AUTO:4,8`: Längen ≤4 → 0, 5 - 8 → 1, ≥9 → 2
`tie_breaker`	Bei einer Suche wird meist in mehreren Feldern gleichzeitig gesucht, etwa im Titel, in der Marke und in der Beschreibung. Das System bewertet jedes Feld separat. Zuerst zählt immer das Feld mit der besten Übereinstimmung (z. B. der Titel). `tie_breaker` legt fest, wie stark zusätzliche Treffer in den anderen Feldern den Gesamtscore mittragen. - Mit `tie_breaker = 0.0` zählt nur das beste Feld; Treffer in weiteren Feldern bringen keinen Zusatzpunkt. - Mit einem moderaten Wert (z. B. 0.2 - 0.4) liefern die anderen Felder einen kleinen Bonus; Treffer in mehreren Feldern werden also sichtbar, ohne das Ranking zu dominieren. - Mit 1.0 würden alle Felder voll addiert; das ist selten sinnvoll, weil schwächere Treffer aus langen Beschreibungen sonst zu viel Gewicht bekommen. Beispiel Ein Begriff passt sehr gut im Titel (Score 10), mittel in Marke (6) und schwach in Beschreibung (3). - 0.0 → Gesamtscore ≈ 10 (nur Titel zählt). - 0.3 → Gesamtscore ≈ 10 + 0.3×(6+3) = 12.7 (Titel bleibt führend, die anderen Felder helfen ein wenig).

Datenfelder

Mit fields_config wird festgelegt, welche Datenfelder in den Suchindex aufgenommen werden und wofür sie genutzt werden (Suche, Anzeige, Filter, Sortierung, Teilwortsuche, Varianten, Kategorien). Änderungen an diesem Block werden nach Neustart des Suchmoduls aktiv. Grundstruktur

fields_config:
  search_fields:
    - {...}
    - {...}
  display_fields:
    - {...}
    - {...}
  filter_fields:
    {...}
  sort_fields:
    - {...}
    - {...}
  ngram_fields:
    - "..."
    - "..."
  variant_fields:
    - "..."
    - "..."
  category_field: ""

Parameterbeschreibung

Parameter	Beschreibung
`search_fields`	Definition der Felder, in denen gesucht werden soll (siehe Abschnitt Search Fields).
`display_fields`	Angabe der Felder, die im Suchergebnis an das Frontend übergeben werden (siehe Abschnitt Display Fields).
`filter_fields`	Definition der verfügbaren Filter und deren Typen im Such-Frontend (siehe Abschnitt Filter Fields).
`sort_fields`	Angabe der Felder, nach denen die Ergebnisse sortiert werden können (siehe Abschnitt Sort Fields).
`ngram_fields`	Festlegung der Felder, für die die Teilwortsuche (N-Gram-Suche) aktiv ist (siehe Abschnitt Ngram Fields).
`variant_fields`	Definition der Felder, die Produktvarianten kennzeichnen (siehe Abschnitt Variant Fields).
`category_field`	Angabe des Feldes, das die Kategorie-IDs enthält (siehe Abschnitt Category Field).

Datenfelder für die Suche (search_fields)

In diesem Abschnitt wird festgelegt, in welchen Feldern die Suche tatsächlich durchgeführt wird. Ohne definierte Suchfelder kann keine inhaltliche Suche stattfinden. Die Auswahl der Felder hängt vom jeweiligen Shop ab, typischerweise werden Produktname, Beschreibung, Kategoriebezeichnungen, Marke/Hersteller oder Farbvarianten angegeben. Standardkonfiguration

fields_config:
  ...
  search_fields:
    - field: name
      boost: 3
    - field: descr
      boost: 2
    - field: brand
      boost: 1.5

Parameterbeschreibung

Parameter	Beschreibung
`field`	Name des Datenfeldes, das in den Suchindex aufgenommen und somit auch durchsucht werden soll. Es muss der technische Feldname des Datenfelds aus dem Datenfeed angegeben werden, das diese Information enthält, z.B. - Produktename (`name`) - Produktbeschreibung (`descr`) - Marke (`brand`) - etc.
`boost`	Optionaler Relevanzfaktor für das angegebene Datenfeld. Die Relevanzwerte reichen von 1 (niedrig) bis 5 (hoch). Höhere Werte bedeuten, dass das Feld bei der Berechnung des Suchergebnisses stärker gewichtet wird.

Datenfelder im Such-Response (display_fields)

In diesem Abschnitt wird festgelegt, welche Felder im Such-Response an das Shop-Frontend übergeben werden. Diese Felder können anschließend direkt in den WebComponents zur Anzeige verwendet werden. Standardmäßig wird nur die Produktnummer bzw. der Produktindex zurückgegeben, da im Standard über diesen Index die Produktdaten aus der Shopdatenbank geladen und durch die WEBSALE Template-Engine im Frontend dargestellt werden. Wenn die Darstellung der Produkte nicht über das Laden der Shopdatenbank und somit nicht über die WEBSALE Template-Engine erfolgen soll, müssen in diesem Abschnitt alle Felder ergänzt werden, die für die Anzeige im Frontend benötigt werden. z. B. Preis, Marke, Produktbild usw. Weitere Informationen siehe Integration in die Templates (Storefront). Standardkonfiguration

fields_config:
  ...
  display_fields:
    - field: baseprodindex
    - field: prodindexbase

Parameterbeschreibung

Parameter	Beschreibung
`field`	Es muss der technische Feldname des Produktdatenfelds aus dem Datenfeed angegeben werden.

Datenfelder für die Filter (filter_fields)

In diesem Abschnitt wird festgelegt, welche Filter im Such-Frontend verfügbar sind und nach welchen Feldwerten gefiltert werden kann. Das Filtersystem unterstützt verschiedene Typen von Filtern, die direkt über die Konfiguration definiert werden. Je nach Datentyp oder Anwendungsfall können so einfache Auswahlfilter, Preisbereiche oder benutzerdefinierte Filterlogiken erstellt werden. Unterstützte Filtertypen:

Terms-Filter (terms) - exakte Werte, z. B. Marken, Farben, Kategorien
Range-Filter (range) - numerische Wertebereiche, z. B. Preis, Bewertung
Custom-Filter (custom) - benutzerdefinierte Bedingungen (z. B. „salesrank ≤ 1000”)
Default-Filter (default) - automatisch aktive Filter (z. B. „nur verfügbare Produkte”)

Standardkonfiguration

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:
      # wird dauerhaft und sozusagen "nicht ersichtlich" angewendet, sorgt dafür,
      # dass die Suche wirklich nur "verfügbare Produkte ang´zeigt"
      - type: default
        op_type: gt
        filter_value: 0
      # das der Customer entscheiden kann, dass er auch nicht verfügbare
      # Produkte angezeigt bekommt
      - type: custom
        label: "Nicht verfügbare Artikel"
        op_type: rm

Terms-Filter farbgrp für Farben.
Range-Filter price für den Preis (von - bis)
Custom-Filter salesrank der Produkte mit einem Verkaufsrang (salesrank) kleiner oder gleich 1000 filtert
Custom-Filter rating der Produkte mit einer durchschnittlichen Kundenbewertung (rating) größer oder gleich 4 filtert
Custom-Filter new_field der Produkte filtert, die mit Neu (new_field) gekennzeichnet sind
Default-Filter inventory, der standardmäßig alle nicht verfügbaren Produkte ausfiltert, kombiniert mit einem Custom-Filter, der es ermöglicht, diesen Default-Filter zu entfernen und damit auch „nicht verfügbare” Produkte anzuzeigen.

Parameterbeschreibung

Parameter	Beschreibung
`<feldname_datenfeed>`	Technischer Feldname des Datenfelds aus dem Datenfeed, auf das sich der Filter bezieht, z. B.: - Farbe → `farbgrp` - Preis → `price` - Verkaufsrang → `salesrank` - Lagerbestand → `inventory` Werden mehrere Filter auf dasselbe Feld angewendet, muss eine Liste konfiguriert werden. Jeder Listeneintrag beginnt mit einem Bindestrich (`-`). Ein Beispiel dafür ist die Filterdefinition für `inventory` mit einem Default- und einem Custom-Filter (siehe oben: Codebeispiel für die Standardkonfiguration).
`type`	Typ des Filters: `terms`, `range`, `custom` oder `default`. Neben kundenspezifischen (dynamischen) Filtern stehen im Standard bereits vordefinierte `custom`- und `default`-Filter zur Verfügung, z. B. salesrank, rating, new_field oder inventory.
`label`	Optionaler Anzeigename des Filters, der im Frontend dargestellt wird
`op_type`	Bedingungstyp für benutzerdefinierte Filter. Legt fest, wie der Vergleich des Feldwerts erfolgen soll. Verfügbare Operatoren: - `eq` – equal → gleich - `lt` – less than → kleiner als - `lte` – less than or equal → kleiner oder gleich - `gt` – greater than → größer als - `gte` – greater than or equal → größer oder gleich - `rm` – remove → entfernt einen zuvor gesetzten Filter (z. B. zur Aufhebung eines Default-Filters) Nur für Filter des `type: custom` und `type: default` relevant.
`filter_value`	Vergleichswert, mit dem die Filterbedingung geprüft wird. Wird zusammen mit `op_type` verwendet, um festzulegen, welche Produkte ein- oder ausgeschlossen werden. Beispiele: - `0` bei `inventory` → zeigt nur Produkte mit einem Lagerbestand größer 0 - `true` bei `new_field` → zeigt nur Produkte, die als „neu” gekennzeichnet sind Nur relevant für Filter des Typs `custom` und `default`. Über `filter_value` können auch Produkte ausgeschlossen werden.

Ausschluss bestimmter Produkte (filter_fields)

Standardmäßig erscheinen alle aktiven Produkte in der Suche. Ausschluss bestimmter Produkte erfolgt innerhalb von filter_fields. Über filter_fields können Produkte regelbasiert ausgeschlossen werden, ohne sie offline zu nehmen. Dieser Abschnitt beschreibt die Konfiguration im Suchmodul; aktive Regeln filtern die betroffenen Artikel zur Laufzeit aus den Suchergebnissen. Beispielkonfiguration filter_fields

filter_fields:

  # Ausschluss: Produktnummer enthalten "99", "88" ODER "77"
  produktnummer:
    type: default
    op_type: neq
    filter_value:
      - "99*"
      - "*88"
      - "*77*"

  # Ausschluss: Kategorie ist "Sonderposten" ODER "Testkategorie"
  category:
    type: default
    op_type: neq
    filter_value:
      - "Sonderposten"
      - "Testkategorie"

  # Ausschluss: Marke ist "adidas" und z.B. auch "adidas originals" ODER "Puma"
  brand:
    type: default
    op_type: neq
    filter_value:
      - "adidas*"
      - "Puma"

  # Ausschluss: Reduziert/SALE ist "true", d.h. ein Produkt ist im SALE resp. reduziert
  is_reduced:
    type: default
    op_type: eq
    filter_value: true

Parameterbeschreibung filter_fields Jeder Eintrag unter filter_fields ist eine Regel pro Datenfeld. Diese Regel wird bei jeder Suche geprüft und entscheidet, ob ein Produkt in die Ergebnisliste darf oder nicht.

Parameter	Beschreibung
`filter_value`	Vergleichswert(e) der Regel. d.h es wird definiert wogegen verglichen wird. Mehrere Felder unter `filter_fields` werden UND verknüpft (alle Regeln müssen erfüllt sein). Mögliche Eingaben / Werte beziehen sich auf den Datentyp des Datenfeldes im Suchindex: - Datentyp `Text`: Unterstützt Text und ``-Wildcards (`TEST` = beginnt mit TEST, `TEST` = endet mit TEST, `TEST*` = enthält TEST). Mehrere Werte können als Array angegeben werden, ODER-Logik innerhalb des Feldes. - Datentyp `Bool/Zahl`: ohne Wildcards, exakt angeben, z.B. `true`/`false`, `0`/`1` usw.

Mehr Informationen zu den filter_fields sowie eine vollständige Übersicht der Parameter siehe Abschnitt Datenfelder für die Filter (filter_fields)

Datenfelder für die Sortierung (sort_fields)

Dieser Block wird nur konfiguriert, wenn die UI-Komponente <ws-sort-box use-api="true"> verwendet wird. In diesem Fall liest die Komponente die Einträge aus sort_fields und generiert automatisch eine Select-Box mit allen konfigurierten Sortieroptionen. Änderungen an sort_fields sind dadurch sofort im Frontend sichtbar – ohne Anpassung des Templates. Wird use-api="false" genutzt, ist sort_fields nicht erforderlich; die Sortier-UI wird dann manuell über das Template bereitgestellt. Mehr zur UI-Komponente ws-sort-box finden Sie hier. Standardkonfiguration

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

Parameterbeschreibung

Parameter	Beschreibung
`field`	Es muss der technische Feldname des Datenfelds aus dem Datenfeed angegeben werden, das für die Sortierung verwendet werden soll.
`label`	Definition der im Frontend angezeigten Sortierbezeichnungen. Wenn kein Label angegeben ist, wird die Sortierung nicht erstellt.
`asc`	Anzeigename der absteigenden Sortierung, z. B. Preis absteigend
`desc`	Anzeigename der aufsteigenden Sortierung, z. B. Preis aufsteigend

Datenfelder für Teilwortsuche (ngram_fields)

In diesem Abschnitt wird festgelegt, für welche Felder die Teilwortsuche (N-Gram-Suche) aktiviert wird. Die Teilwortsuche ermöglicht es, auch bei unvollständigen oder teilweise passenden Suchanfragen Treffer zu finden, z. B. liefert die Eingabe „jack” auch Ergebnisse wie Jacke, Jacket oder Jackett. Beim Aufbau des Suchindex werden für die hier definierten Felder sogenannte N-Gram-Token erzeugt. Dadurch können Suchbegriffe bereits während der Eingabe oder bei ungenauer Schreibweise erkannt werden. Typische Felder sind Produktname, Beschreibung oder Artikelnummern. Standardkonfiguration

fields_config:
  ...
  ngram_fields:
    - name
    - descr
    - number

Parameterbeschreibung

Parameter	Beschreibung
`ngram_fields`	Liste der technischen Feldnamen des Datenfelds aus dem Datenfeed, für die die Teilwortsuche aktiviert werden soll.

Variantenfelder für Filter (variant_fields)

In diesem Abschnitt wird festgelegt, welche Variantenattribute bei der Ermittlung von Filterwerten berücksichtigt werden sollen. Da die Berechnung von Filteroptionen (Aggregation) über viele Variantenprodukte performancekritisch ist, müssen die relevanten Variantenfelder hier explizit angegeben werden. Nur die in diesem Abschnitt definierten Felder fließen bei der Filterermittlung ein und beziehen dabei die Varianten eines Produkts mit ein. Standardkonfiguration

fields_config:
  ...
  variant_fields:
    enabled: true
    fields:
      - size
      - color

In diesem Beispiel werden die Felder Farbe (color) und Größe (size) als Variantenfelder definiert.

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert die Berücksichtigung von Variantenattributen aus dem Datenfeed, um diese als Filterwerte bereitzustellen.
`fields`	Liste der technischen Feldnamen von Variantenattributen.

Kategoriefelder (category_field)

In diesem Abschnitt wird der Feldname eingetragen, der die Kategorie-IDs (Kategorieindizes) enthält. Der hier konfigurierte Feldname wird vom Suchmodul verwendet, um den Kontext (Suchergebnisseite vs. Kategorieseite) korrekt zu bestimmen und Produkte nach einer Suche, Filterung oder Sortierung in der richtigen Kategorie zu öffnen. Der Standardwert ist in der Regel bereits gesetzt und sollte nicht geändert werden. Standardkonfiguration

fields_config:
  ...
  category_field: catids

Parameterbeschreibung

Parameter	Beschreibung
`category_field`	Enthält immer den Feldname des Datenfelds aus dem Datenfeed, das die Kategorie IDs enthält.

Ausnahmen zur globalen Fuzzy-Logik (fuzzy_filter)

fuzzy_filter definiert gezielte Ausnahmen zur globalen Fuzzy-Logik. Damit lassen sich einzelne Begriffe stets exakt suchen (ohne Fuzzy), um Verwechslungen zu vermeiden, und ganze Felder von Fuzzy ausschließen (z. B. Produkt-IDs). Dieser Abschnitt dient der Feinsteuerung, wenn das Standardverhalten zu unerwünschten Treffern führt oder bestimmte Datenfelder grundsätzlich exakt behandelt werden sollen. Standardkonfiguration

...
fuzzy_filter:
  enabled: true
  list: []
  excluded_fields:
    - productnumber
    - productid
...

Fuzzy-Suche aktiviert: Tippfehler werden gemäß der globalen Fuzzy-Toleranz in der search_config toleriert (z. B. Distanz abhängig von Wortlänge).
Keine globalen Wort-Ausschlüsse: Die Liste list ist absichtlich leer, da kritische Begriffe je Shop variieren und individuell gepflegt werden sollten.
Felder ohne Fuzzy: In productnumber und productid wird kein Fuzzy-Match durchgeführt (exakte Suche auf IDs/SKUs).

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) den Fuzzy-Filter. Wenn `true`, wird der Fuzzy-Filter angewendet, d. h. bestimmte Felder oder Begriffe (laut `excluded_fields` bzw. `list`) werden von der Fuzzy-Suche ausgeschlossen. Wenn `false`, ist der Fuzzy-Filter inaktiv, und die Fuzzy-Suche greift auf alle Felder ohne Einschränkung zu.
`list`	Liste von Begriffen, die ohne Fuzzy gesucht werden (exakt). Diese Wörter werden exakt gesucht, auch wenn Tippfehler vorliegen. Nützlich für kritische Begriffe oder Begriffe mit hoher Verwechslungsgefahr. Beispiel: `list:` `- westen` `- western` Wenn hier `westen` und `western` eingetragen werden, gelten für diese beiden Wörter keine Tippfehler-Toleranzen; dadurch werden Verwechslungen (z. B. Kategorie Western vs. Kleidungsstück Westen) verhindert.
`excluded_fields`	Felder, in denen Fuzzygrundsätzlich nicht angewendet werden soll, z. B. `productnumber`, `productid` für exakte ID-Suche

Sonderzeichen-Handhabung (punctuation_filter)

Der punctuation_filter steuert die Behandlung von Sonderzeichen in Suchanfragen und indexierten Begriffen. Damit lassen sich Suchergebnisse vereinheitlichen und Null-Treffer durch unterschiedliche Schreibweisen (z. B. USB-C, USB C, USBC) vermeiden. Eine Anpassung ist erforderlich, wenn vom Standardverhalten abgewichen werden soll – etwa wenn bestimmte Sonderzeichen zusätzlich erhalten bleiben sollen (z. B. & bei Markennamen) oder wenn weitere Zeichen entfernt werden müssen. Standardkonfiguration

punctuation_filter:
  enabled: true               # (de-)aktivierung der Funktion
  replace_with_space:         # Zeichen die mit einem Whitespace ersetzt werden sollen
    - "-"
    - "/"
  type: black                 # white = whitelist; black = blacklist
  list:                       # Liste von Zeichen die entfernt/behalten werden sollen (je nach type)
    - "_"
    - "&"
    - "."

Bindestriche (-) und Schrägstriche (/) werden durch Leerzeichen ersetzt. → „USB-C” = „USB C”, „Herren/Hemd” = „Herren Hemd”.
Unterstriche (_), kaufmännisches Und (&) und Punkte (.) werden entfernt. → „Winter_Pullover” = „Winter Pullover”, „Jack&Jones” = „Jack Jones”, „PS.5” = „PS5”.
Alle anderen Zeichen bleiben erhalten.

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) die Sonderzeichen-Normalisierung.
`replace_with_space`	Liste von Zeichen, die nicht gelöscht, sondern durch ein Leerzeichen ersetzt werden. Sinnvoll für Trennzeichen, die eine Wortgrenze markieren sollen (z. B. `-`, `/`).
`type`	Legt fest, wie die Liste interpretiert wird: - `black` = Blacklist → Nur die angegebenen Zeichen werden entfernt, alle anderen bleiben erhalten. - `white` = Whitelist → Nur die angegebenen Zeichen bleiben erhalten, alle anderen werden entfernt.
`list`	Die konkrete Zeichenliste, die je nach `type` entfernt oder behalten wird.

Toleranz für das Ignorieren von Stopwörtern (stopwords_filter)

Die Konfiguration im Suchmodul legt ausschließlich fest, ob die beim Import definierte Stopwort-Liste während der Anfrageauswertung berücksichtigt wird. Mit stopwords_filter wird das Ignorieren von Stopwörtern zur Laufzeit ein- oder ausgeschaltet: Ist es aktiv, werden Begriffe aus der hinterlegten Liste vor dem Matching entfernt, während Wörter aus der Whitelist nicht entfernt und damit ganz normal gewertet werden. Die inhaltliche Zusammenstellung der Stopwort-Liste selbst erfolgt nicht im Suchmodul, sondern vollständig im Import-Modul. Standardkonfiguration stopwords_filter

stopwords_filter:
  enabled: true

Parameterbeschreibung stopwords_filter

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) die Toleranz für das Ignorieren von Stopwörtern. Ist nur sinnvoll in Kombination mit einer gepflegten Stopwort-Liste aus dem Import.

Grammatikalische Flexion (lemmatization)

In diesem Abschnitt wird festgelegt, ob und in welcher Sprache Suchbegriffe während der Suche auf ihre grammatikalische Grundform reduziert werden. Dadurch erkennt das System, dass unterschiedliche Wortformen – etwa „rote Hemden”, „rotes Hemd” oder „Hemd in Rot” – denselben Begriff meinen. Die Funktion verbessert die semantische Erkennung und sorgt für natürlichere Suchergebnisse. Für technische Felder (z. B. Produktnummern, Modellcodes) kann die Lemmatization deaktiviert bleiben, um exakte Zeichenfolgen zu wahren.

Von der Verwendung der grammatikalischen Flexion (Lemmatisierung) zur Suchzeit wird abgeraten. Suchanfragen bestehen im E-Commerce typischerweise aus nur 1–3 Wörtern und liefern damit nicht genügend Kontext für eine zuverlässige Lemmatisierung in deutscher Sprache. Dadurch kann die Nutzerabsicht verfälscht werden (z. B. wird aus „blau” fälschlich „blauen”) und die Suche liefert unvorhersehbare oder fehlende Ergebnisse. In der Praxis werden die relevanten Varianten bereits durch die vorhandenen Match-Strategien (u. a. Exact, Prefix, N-gram, Fuzzy, Wildcard) abgedeckt. Falls spezielle Fälle abgebildet werden müssen, ist ein Synonym-Mapping die bessere Alternative, da es kontrollierbar und nachvollziehbar ist. Die Lemmatisierung kann weiterhin zur Index-Zeit sinnvoll sein (z. B. bei längeren Produkttexten mit ausreichend Kontext), sollte jedoch nicht bei der Verarbeitung der Suchanfrage aktiviert werden.

Standardkonfiguration

lemmatization:
  enabled: true
  language: de

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) die grammatikalische Reduktion von Suchbegriffen auf ihre Grundform. Grundlage sind die sprachspezifischen Wortstämme und Modelle der NLP-Bibliotheken spaCy und Simplemma. Bei deaktivierter Einstellung erfolgt eine wortgenaue Suche ohne sprachliche Vereinheitlichung.
`language`	Definiert die Sprache, für die der Lemmatizer angewendet wird. Aktuell verfügbar: - Deutsch (`de`) = Standard - Englisch (`en`) - Spanisch (`es`) - Französisch (`fr`) - Italienisch (`it`) - Niederländisch (`nl`) - Portugiesisch (`pt`) - Dänisch (`da`) - Tschechisch (`cs`) - Polnisch (`pl`) - Finnisch (`fi`) - Indonesisch (`id`) - Slowakisch (`sk`) - Türkisch (`tr`) - Schwedisch (`sv`) - Norwegisch Bokmål (`nb`) Je nach gewählter Sprache werden die entsprechenden Sprachmodelle von spaCy und Simplemma genutzt, um grammatikalische Varianten korrekt zu erkennen.

Index-Konfiguration (index_configs)

Über index_configs wird pro Subshop gesteuert, welche Indizes bei der Suche zur Laufzeit aktiv sind und wie sie sich verhalten. Ein Index muss sowohl im Importmodul als auch hier im Suchmodul aktiviert sein, um wirksam zu werden. Grundstruktur

index_configs:
  product:        # Hauptindex für Produktsuche
    {...}
  completion:     # Index für Autovervollständigung
    {...}
  category:       # Index für Kategoriesuche
    {...}
  content:        # Index für statische Inhaltsseiten
    {...}

Produkte (Product-Index)

Der Product-Index ist der Hauptindex und bildet die Grundlage jeder Produktsuche. Er ist in der Regel immer aktiv. Die inhaltliche Konfiguration, also welche Felder durchsucht, gefiltert oder angezeigt werden, erfolgt über fields_config. Über index_configs.product wird primär gesteuert, ob der Index zur Laufzeit aktiv ist. Beispielkonfiguration

index_configs:
  product:
    enabled: true

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) den Produkt-Index im Suchmodul. Sollte in der Regel auf `true` gesetzt bleiben. Muss auch im Importmodul aktiviert sein (`index_configs.product.enabled`).

Autovervollständigung (Completion-Index)

Der Completion-Index wird für die Autovervollständigung von Suchbegriffen verwendet. Wie beim Product-Index beschränkt sich die Konfiguration hier auf die Aktivierung des Index - weitergehende Einstellungen (z.B. Fuziness) werden über suggest_config gesteuert, die inhaltliche Grundlage wird beim Import festgelegt. Beispielkonfiguration

index_configs:
  completion:
    enabled: true

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert (`true`) oder deaktiviert (`false`) den Completion-Index im Suchmodul. Muss auch im Importmodul aktiviert sein (`index_configs.completion.enabled`).

Kategorien (Category-Index)

Wenn beim Import ein Kategorie-Index angelegt wurde, kann dieser im Suchmodul pro Subshop aktiviert werden. Dadurch werden neben Produkten (und ggf. Inhaltsseiten) auch Kategorien in der Suche berücksichtigt. Beispielkonfiguration

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

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert die Suche im Kategorie-Index für den jeweiligen Subshop.
`custom_config`	Konfigurationsblock für die Kategoriesuche. Legt fest, welche Felder durchsucht und welche in der Antwort zurückgegeben werden. Dieser Key wird für zukünftige zusätzliche Indizes analog übernommen.
`search_fields`	Liste der Felder, die bei einer Kategoriesuche durchsucht werden. Sollte immer mindestens `cat_str` und `cat_str_path` enthalten. Pro Feld kann ein `boost`-Wert angegeben werden. Alle untergeordneten Keys sind in diesem Abschnitt dokumentiert.
`display_fields`	Liste der Felder, die in der Suchantwort zurückgegeben werden. Benötigt wird mindestens `cat_id`. Alle untergeordneten Keys sind in diesem Abschnitt dokumentiert.
`search_config`	Optionaler Konfigurationsblock zur Steuerung der Sucharten für den Kategorie-Index. Analog zur Basiskonfiguration des Suchmoduls können die einzelnen Sucharten (`exact`, `prefix`, `wildcard`, `ngram`, `fuzzy`) gezielt aktiviert, deaktiviert und gewichtet werden.

Inhaltsseiten (Content-Index)

Wenn beim Import ein Content-Index angelegt wurde, kann dieser im Suchmodul pro Subshop aktiviert werden. Dadurch werden neben Produkten (und ggf. Kategorien) auch statische Inhaltsseiten (z. B. „Über uns”, AGB, Impressum) in der Suche berücksichtigt. Beispielkonfiguration

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

Parameterbeschreibung

Parameter	Beschreibung
`enabled`	Aktiviert die Suche im Content-Index für den jeweiligen Subshop.
`custom_config`	Konfigurationsblock für die Inhaltsseiten-Suche.
`search_fields`	Liste der Felder, die für die Volltextsuche im Content-Index herangezogen werden. Beim Content-Index sind diese Felder fest vorgegeben (z.B. `title`, `content`).
`display_fields`	Liste der Felder, die in der Suchantwort enthalten sein müssen (z. B. `source` zum Nachladen des Inhalts und `title` als Label). Auch hier sind die Felder fest je Index-Art definiert.
`search_config`	Optionaler Konfigurationsblock zur Steuerung der Sucharten für den Content-Index. Analog zur Basiskonfiguration des Suchmoduls können die einzelnen Sucharten (`exact`, `prefix`, `wildcard`, `ngram`, `fuzzy`) gezielt aktiviert, deaktiviert und gewichtet werden.

​Importkonfiguration & Konfiguration des Suchmoduls

​Importmodul der Suche

​Suchmodul

​Datenfeed im Dataflow Manager

​Konfigurationshierarchie (ab v1.12.x / v.1.11.x)

​Globale Konfiguration (global_configs)

​Sprachkonfiguration (language_configs)

​Subshop-Konfiguration (subshop_configs)

​Konfiguration des Importmoduls

​Datenfeed-Konfiguration

​Subshopkonfiguration im Importmodul

​Toleranz für das Ignorieren von Stoppwörtern (stopwords)

​Synonyme (synonyms)

​Grammatikalische Flexion (lemmatization)

​Kategorien

​Inhaltsseiten in den Suchindex aufnehmen

​Konfiguration des Suchmoduls

​Suchvorschläge (suggest_config)

​Filter (filter_config)

​Subshopkonfiguration für das Suchmodul

​Basiskonfiguration des Suchmoduls (search_config)

​Exakte Suche (exact)

​Präfix-Suche (prefix)

​Wildcard-Suche (wildcard)

​Teilwortsuche / N-Gram-Suche (ngram)

​Fehlertolerante Suche & Levenshtein-Distanz (fuzzy)

​Datenfelder

​Datenfelder für die Suche (search_fields)

​Datenfelder im Such-Response (display_fields)

​Datenfelder für die Filter (filter_fields)

​Ausschluss bestimmter Produkte (filter_fields)

​Datenfelder für die Sortierung (sort_fields)

​Datenfelder für Teilwortsuche (ngram_fields)

​Variantenfelder für Filter (variant_fields)

​Kategoriefelder (category_field)

​Ausnahmen zur globalen Fuzzy-Logik (fuzzy_filter)

​Sonderzeichen-Handhabung (punctuation_filter)

​Toleranz für das Ignorieren von Stopwörtern (stopwords_filter)

​Grammatikalische Flexion (lemmatization)

​Index-Konfiguration (index_configs)

​Produkte (Product-Index)

​Autovervollständigung (Completion-Index)

​Kategorien (Category-Index)

​Inhaltsseiten (Content-Index)

Importkonfiguration & Konfiguration des Suchmoduls

Importmodul der Suche

Suchmodul

Datenfeed im Dataflow Manager

Konfigurationshierarchie (ab v1.12.x / v.1.11.x)

Globale Konfiguration (`global_configs`)

Sprachkonfiguration (`language_configs`)

Subshop-Konfiguration (`subshop_configs`)

Konfiguration des Importmoduls

Datenfeed-Konfiguration

Subshopkonfiguration im Importmodul

Toleranz für das Ignorieren von Stoppwörtern (stopwords)

Synonyme (synonyms)

Grammatikalische Flexion (lemmatization)

Kategorien

Inhaltsseiten in den Suchindex aufnehmen

Konfiguration des Suchmoduls

Suchvorschläge (suggest_config)

Filter (filter_config)

Subshopkonfiguration für das Suchmodul

Basiskonfiguration des Suchmoduls (search_config)

Exakte Suche (exact)

Präfix-Suche (prefix)

Wildcard-Suche (wildcard)

Teilwortsuche / N-Gram-Suche (ngram)

Fehlertolerante Suche & Levenshtein-Distanz (fuzzy)

Datenfelder

Datenfelder für die Suche (search_fields)

Datenfelder im Such-Response (display_fields)

Datenfelder für die Filter (filter_fields)

Ausschluss bestimmter Produkte (filter_fields)

Datenfelder für die Sortierung (sort_fields)

Datenfelder für Teilwortsuche (ngram_fields)

Variantenfelder für Filter (variant_fields)

Kategoriefelder (category_field)

Ausnahmen zur globalen Fuzzy-Logik (fuzzy_filter)

Sonderzeichen-Handhabung (punctuation_filter)

Toleranz für das Ignorieren von Stopwörtern (stopwords_filter)

Grammatikalische Flexion (lemmatization)

Index-Konfiguration (index_configs)

Produkte (Product-Index)

Autovervollständigung (Completion-Index)

Kategorien (Category-Index)

Inhaltsseiten (Content-Index)