OpenSearch Attribut-Mapping in Magento 2 konfigurieren

1. Warum das Standard-Mapping an Grenzen stößt

Ein OpenSearch Attribut-Mapping beschreibt, wie ein Magento-Produktattribut im Suchindex gespeichert wird: als Volltext-Feld mit Analyzer, als exakter Keyword-Wert, als Zahl oder als Datum. Magento generiert dieses Mapping standardmäßig automatisch aus dem EAV-Attributtyp, aber diese automatische Ableitung ist bewusst konservativ gehalten. Ein varchar-Attribut wird fast immer als text-Feld mit dem Standard-Analyzer abgebildet, egal ob es sich um eine Produktbeschreibung, eine SKU-Ergänzung oder ein technisches Kürzel handelt.

In der Praxis führt das zu Problemen, die erst auffallen, wenn der Katalog wächst. Eine Artikelnummer wie ABC-1234-XL wird vom Standard-Analyzer in Tokens wie abc, 1234 und xl zerlegt, was für Volltextsuche in Beschreibungen sinnvoll ist, aber exakte Codesuchen verwässert. Ein individuelles OpenSearch Attribut-Mapping löst genau dieses Problem, indem es pro Attribut den passenden Feldtyp und Analyzer definiert, statt sich auf die pauschale Magento-Ableitung zu verlassen.

Der zweite Grund für ein eigenes OpenSearch Attribut-Mapping ist Performance. Jedes zusätzliche analysierte Feld vergrößert den Index und verlangsamt Indexierung wie auch Aggregationen für Facetten. Wer bewusst entscheidet, welche Attribute als text, welche als keyword und welche gar nicht indexiert werden, reduziert die Indexgröße spürbar und beschleunigt sowohl die Volltextsuche als auch die Layered Navigation.

2. Wie Magento Attribute auf OpenSearch-Feldtypen abbildet

Magento nutzt für die Ableitung des OpenSearch Attribut-Mapping die Klasse Magento\Elasticsearch\Model\Adapter\FieldMapper\ProductFieldMapper, die für jedes Attribut über den Backend-Typ (backend_type) und die Eingabeart (frontend_input) entscheidet, welcher Feldtyp im Index entsteht. Ein select-Attribut wird typischerweise als keyword gemappt, ein text- oder textarea-Feld als analysierter text-Typ, numerische Attribute als float oder integer.

Zusätzlich unterscheidet Magento zwischen dem eigentlichen Suchfeld (mit Suffix, z. B. attribut_code_value) und dem Feld für Facetten-Aggregationen (häufig mit dem Suffix attribut_code ohne weitere Analyse). Diese Doppelspurigkeit erklärt, warum ein Attribut im Index oft zweimal vorkommt: einmal analysiert für die Suche, einmal als keyword für exakte Filterung und Aggregation. Wer das OpenSearch Attribut-Mapping verstehen will, muss diese beiden Felder getrennt betrachten, sonst wirken Änderungen an einer Stelle nicht wie erwartet.

{
  "properties": {
    "sku": {
      "type": "keyword",
      "ignore_above": 256
    },
    "name": {
      "type": "text",
      "analyzer": "default"
    },
    "description": {
      "type": "text",
      "analyzer": "default"
    },
    "color": {
      "type": "keyword"
    },
    "price": {
      "type": "scaled_float",
      "scaling_factor": 100
    }
  }
}

Dieser Ausschnitt zeigt ein typisches, unangepasstes OpenSearch Attribut-Mapping: sku als exakter Keyword-Wert, name und description als analysierter Text, color als Keyword für Facetten, price als skalierter Float. Genau diese Struktur ist der Ausgangspunkt für individuelle Anpassungen.

3. search_weight und searchable im Attribut korrekt setzen

Bevor man Code schreibt, lohnt sich der Blick auf die Attributkonfiguration selbst. Im Magento-Backend steuert das Flag Used in Search Results (Datenbankspalte searchable), ob ein Attribut überhaupt in die Volltextsuche einfließt. Das Feld Search Weight (1 bis 10) beeinflusst die Relevanz-Gewichtung dieses Attributs innerhalb der Suchquery und wirkt sich direkt auf das generierte OpenSearch Attribut-Mapping aus, weil das Gewicht in die multi_match-Query mit ^Gewicht-Boost übernommen wird.

Ein häufiger Fehler: Attribute wie interne Lieferantencodes oder technische Notizfelder werden versehentlich auf searchable gesetzt, wodurch sie die Relevanz verwässern und irrelevante Treffer produzieren. Umgekehrt werden Attribute, die eigentlich stark gewichtet werden sollten (Produktname, Kurzbeschreibung mit Modellbezeichnung), oft mit dem Standardgewicht 1 belassen. Ein sauberes OpenSearch Attribut-Mapping beginnt immer mit einer bewussten Durchsicht aller searchable-Attribute und ihrer Gewichtung, bevor überhaupt Code angefasst wird.

Für Facetten ist zusätzlich das Flag Use in Layered Navigation entscheidend. Ein Attribut kann durchaus searchable und gleichzeitig als Filter nutzbar sein, benötigt dafür aber im Index ein zusätzliches, nicht analysiertes Feld für die Aggregation. Wer beide Flags unabhängig voneinander plant, vermeidet später Überraschungen im generierten Mapping.

4. Eigenes Mapping per FieldMapperInterface anpassen

Um ein wirklich individuelles OpenSearch Attribut-Mapping zu erzwingen, reicht die Backend-Konfiguration allein nicht aus. Magento bietet dafür das Interface Magento\AdvancedSearch\Model\Adapter\Mapper\FieldMapperInterface, dessen Implementierungen über die di.xml per virtualType zusammengesetzt werden. Der sauberste Weg ist ein Plugin auf ProductFieldMapper::getAllAttributesTypes() beziehungsweise getFieldName(), das für bestimmte Attributcodes einen abweichenden Feldtyp erzwingt.

<?php

declare(strict_types=1);

namespace Mironsoft\SearchMapping\Plugin;

use Magento\Elasticsearch\Model\Adapter\FieldMapper\ProductFieldMapper;

/**
 * Overrides the field type for specific attributes in the OpenSearch mapping.
 */
final class ForceKeywordMappingPlugin
{
    /** @var array<string,string> Attribute code to forced OpenSearch field type */
    private const FORCED_TYPES = [
        'manufacturer_sku' => 'keyword',
        'ean' => 'keyword',
        'internal_note' => 'none',
    ];

    /**
     * Forces selected attributes to bypass the default type resolution.
     *
     * @param ProductFieldMapper $subject Original field mapper
     * @param array<string,string> $result Resolved attribute types
     * @return array<string,string>
     */
    public function afterGetAllAttributesTypes(
        ProductFieldMapper $subject,
        array $result
    ): array {
        foreach (self::FORCED_TYPES as $attributeCode => $forcedType) {
            if (isset($result[$attributeCode])) {
                $result[$attributeCode] = $forcedType;
            }
        }

        return $result;
    }
}

Die Registrierung erfolgt klassisch per di.xml. Wichtig: Die Attributdaten müssen weiterhin über searchable im Backend gesteuert werden, das Plugin verändert nur den Feldtyp, nicht die Sichtbarkeit im Index. Bei komplexeren Fällen, etwa wenn ein Attribut in mehreren Sprachen unterschiedlich analysiert werden soll, lohnt sich ein eigener virtualType für den FieldMapper statt eines reinen Plugins, weil sich damit auch neue Analyzer-Zuordnungen sauber kapseln lassen.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Elasticsearch\Model\Adapter\FieldMapper\ProductFieldMapper">
        <plugin name="mironsoft_force_keyword_mapping"
                type="Mironsoft\SearchMapping\Plugin\ForceKeywordMappingPlugin"
                sortOrder="10"/>
    </type>
</config>

5. Analyzer und Normalizer für eigene Attribute definieren

Ein Feldtyp allein reicht selten aus, um ein wirklich passendes OpenSearch Attribut-Mapping zu bekommen. Der Analyzer entscheidet, wie ein Textwert in durchsuchbare Tokens zerlegt wird, und genau hier liegt der größte Hebel für Suchqualität. Für Artikelnummern mit festen Trennzeichen empfiehlt sich ein eigener keyword-Normalizer, der Groß- und Kleinschreibung vereinheitlicht, ohne den Wert in Wortteile zu zerlegen. Für mehrsprachige Beschreibungstexte lohnt sich ein sprachspezifischer Analyzer mit Stemming, statt des generischen Standard-Analyzers.

Ein häufiger Anwendungsfall ist ein edge_ngram-Analyzer für Autocomplete-Felder, der Teilstrings bereits ab drei Zeichen indexiert. Dieses Muster gehört ebenfalls zum OpenSearch Attribut-Mapping, weil es ein zusätzliches Feld mit eigenem Analyzer neben dem regulären Suchfeld erzeugt. Wichtig ist, diese Analyzer und Normalizer in den Index-Settings zu registrieren, bevor der Index angelegt wird, denn Analyzer-Konfigurationen lassen sich bei bestehenden Indizes nicht nachträglich ändern, ohne den Index neu anzulegen.

{
  "settings": {
    "analysis": {
      "normalizer": {
        "sku_normalizer": {
          "type": "custom",
          "filter": ["lowercase", "asciifolding"]
        }
      },
      "analyzer": {
        "autocomplete_analyzer": {
          "type": "custom",
          "tokenizer": "autocomplete_tokenizer",
          "filter": ["lowercase"]
        }
      },
      "tokenizer": {
        "autocomplete_tokenizer": {
          "type": "edge_ngram",
          "min_gram": 3,
          "max_gram": 12,
          "token_chars": ["letter", "digit"]
        }
      }
    }
  }
}

Ein Detail, das leicht übersehen wird: Der Normalizer wirkt nur auf keyword-Felder, der Analyzer nur auf text-Felder. Wer beide verwechselt, bekommt entweder keine Wirkung oder einen OpenSearch-Fehler beim Anlegen der Index-Settings. Bei jedem individuellen OpenSearch Attribut-Mapping lohnt sich daher ein kurzer Test über die _analyze-API, bevor die Konfiguration produktiv geschaltet wird.

6. Attribute als Facette in der Layered Navigation nutzbar machen

Damit ein Attribut als Facette in der Layered Navigation erscheint, braucht das OpenSearch Attribut-Mapping ein Aggregations-fähiges Feld, in der Regel ein keyword-Typ ohne Analyzer. Für select- und multiselect-Attribute erledigt Magento das standardmäßig, für Freitextattribute, die nachträglich facettierbar gemacht werden sollen, muss ein zusätzliches keyword-Subfeld angelegt werden, etwa über fields innerhalb der Mapping-Definition.

Ein häufiger Merchandising-Wunsch ist die Facettierung nach Preisspannen mit eigenen, fest definierten Buckets statt der automatischen Magento-Preisstufen. Das lässt sich technisch über eine Range-Aggregation auf dem price-Feld lösen, ohne dass sich am OpenSearch Attribut-Mapping selbst etwas ändern muss, solange der Feldtyp numerisch bleibt. Für kategoriespezifische Facetten, die nur in bestimmten Kategorien angezeigt werden sollen, kombiniert man das Mapping am besten mit der Attributzuordnung zum Attribut-Set, damit irrelevante Filter gar nicht erst in der Aggregation landen.

{
  "aggs": {
    "price_ranges": {
      "range": {
        "field": "price",
        "ranges": [
          { "to": 50 },
          { "from": 50, "to": 150 },
          { "from": 150, "to": 500 },
          { "from": 500 }
        ]
      }
    },
    "color_facet": {
      "terms": { "field": "color", "size": 20 }
    }
  }
}

7. Reindex-Strategie bei Mapping-Änderungen

Jede Änderung am OpenSearch Attribut-Mapping, die den Feldtyp betrifft, erfordert einen vollständigen Reindex, weil OpenSearch bestehende Feldtypen in einem laufenden Index nicht nachträglich ändern lässt. Magentos Indexer legt bei jedem vollständigen Reindex-Lauf einen neuen Index mit Alias-Suffix an und schwenkt den Alias erst nach erfolgreichem Abschluss um, was Zero-Downtime-Reindexierung im Standardfall bereits ermöglicht.

Bei individuellen Mapping-Anpassungen sollte dieser Ablauf getestet werden, bevor er produktiv läuft: Zuerst wird das neue Mapping in einer Staging-Umgebung angelegt, ein vollständiger Reindex durchgeführt und anhand von Stichproben verglichen, ob Suchergebnisse und Facetten weiterhin korrekt funktionieren. Erst danach wandert die Änderung in die Produktion. Ein zu unterschätzendes Risiko: Wird das OpenSearch Attribut-Mapping so verändert, dass ein Feld plötzlich einen anderen Typ hat als in einer alten Version des Frontends erwartet, kann die Suche für einzelne Requests mit einem Mapping-Konflikt fehlschlagen, bis der Cache und alle Fronten konsistent auf die neue Version zeigen.

# Full reindex after mapping changes, non-blocking for the storefront
bin/magento indexer:reindex catalogsearch_fulltext

# Verify the new index exists and alias points to it
curl -s "http://opensearch:9200/_cat/indices?v" | grep magento2

# Compare mapping between the live and staging index
curl -s "http://opensearch:9200/magento2_default_product/_mapping" | jq . > /tmp/mapping.json

8. Mapping inspizieren und Queries direkt testen

Bei Problemen mit Suchergebnissen lohnt sich immer ein direkter Blick auf das tatsächliche OpenSearch Attribut-Mapping, statt Vermutungen anzustellen. Die _mapping-API liefert die vollständige Feldstruktur eines Index, die _analyze-API zeigt, wie ein konkreter Text von einem bestimmten Analyzer zerlegt wird. Diese beiden Endpunkte klären neunzig Prozent aller "warum findet die Suche das nicht"-Fragen schneller als jede Codeanalyse.

Ein bewährtes Vorgehen: Zuerst mit _analyze prüfen, welche Tokens für den Suchbegriff und für das gespeicherte Attribut entstehen. Stimmen die Tokens nicht überein, liegt das Problem im Analyzer oder im OpenSearch Attribut-Mapping, nicht in der Magento-Query-Logik. Erst wenn die Tokens übereinstimmen, aber trotzdem kein Treffer erscheint, lohnt sich der Blick in die generierte Magento-Query, zum Beispiel über den integrierten Profiler oder durch Mitschneiden des tatsächlich an OpenSearch gesendeten Requests.

# Show how the analyzer tokenizes a given text
curl -s -X POST "http://opensearch:9200/magento2_default_product/_analyze" \
  -H "Content-Type: application/json" \
  -d '{"field": "name", "text": "ABC-1234-XL Jacke"}' | jq .

# Show the full mapping for a single field
curl -s "http://opensearch:9200/magento2_default_product/_mapping/field/sku" | jq .

9. Standard-Mapping vs. individuelles Mapping im Vergleich

Die folgende Übersicht fasst zusammen, wann das automatisch generierte OpenSearch Attribut-Mapping ausreicht und wann ein individuelles Mapping notwendig wird.

Der Trend in der Tabelle ist eindeutig: Immer dann, wenn ein Attribut eine spezielle Rolle im Merchandising oder in der Suche spielt, lohnt sich die Investition in ein individuelles OpenSearch Attribut-Mapping. Für generische Textfelder ohne besondere Anforderungen bleibt das Standard-Mapping die richtige, pragmatische Wahl.

10. Zusammenfassung

Ein individuelles OpenSearch Attribut-Mapping beginnt nicht im Code, sondern in der Attributkonfiguration: searchable, search_weight und Use in Layered Navigation legen den Rahmen fest, bevor überhaupt ein Plugin geschrieben wird. Für Attribute mit besonderen Anforderungen, exakte Codes, Autocomplete-Felder oder mehrsprachige Texte, lohnt sich die Implementierung von FieldMapperInterface mit eigenen Analyzern und Normalizern.

Jede Mapping-Änderung, die den Feldtyp betrifft, erfordert einen vollständigen Reindex, den Magentos Alias-Mechanismus im Regelfall ohne Downtime bewältigt. Die _analyze- und _mapping-APIs von OpenSearch sind die schnellsten Werkzeuge, um zu verstehen, warum eine Suche nicht wie erwartet funktioniert, bevor man in der Magento-Codebasis nach Ursachen sucht. Wer diese Reihenfolge einhält, baut ein OpenSearch Attribut-Mapping, das mit dem Katalog mitwächst statt ihn auszubremsen.

11. FAQ: OpenSearch Attribut-Mapping in Magento 2