Custom-Attribute-Mapping in Magento gezielt erweitern

1. Warum Standard-Mapping nicht fuer jedes Attribut passt

Magentos Custom-Attribute-Mapping funktioniert im Standardfall automatisch: Ein neues EAV-Attribut wird angelegt, als "searchable" oder "filterable" markiert, und beim naechsten Reindex taucht es im Elasticsearch-Mapping auf. Fuer die meisten einfachen Attribute wie Farbe, Groesse oder Material ist dieser automatische Weg vollkommen ausreichend. Problematisch wird es, sobald ein Attribut Anforderungen hat, die die Standardableitung nicht abdeckt: ein eigener Analyzer fuer bessere Volltextsuche, ein spezielles numerisches Format, oder eine Feldstruktur, die von mehreren Quellattributen zusammengesetzt wird.

Das Custom-Attribute-Mapping in Magento basiert auf einer Kette aus FieldMapper- und FieldType-Resolver-Klassen, die ueber di.xml konfigurierbar sind. Diese Konfigurierbarkeit ist bewusst so gestaltet, dass Entwickler nicht in den Magento-Core eingreifen muessen, um das Verhalten fuer einzelne Attribute zu aendern. Wer versteht, an welcher Stelle dieser Kette ein Custom-Attribut-Mapping ansetzt, kann praezise steuern, wie ein Attribut im Index landet, ohne die Standardlogik fuer alle anderen Attribute zu beeinflussen.

Dieser Artikel zeigt Schritt fuer Schritt, wie ein eigenes Custom-Attribute-Mapping aufgebaut wird: von den relevanten Interfaces ueber die Steuerung durch Attributflags bis zu einem vollstaendigen Beispiel mit eigenem Analyzer fuer ein Boolean-Attribut.

2. Der FieldMapper-Mechanismus in di.xml

Der zentrale Baustein fuer jedes Custom-Attribute-Mapping ist das Interface Magento\Elasticsearch\Model\Adapter\FieldMapperInterface. Seine Standardimplementierung wird in der di.xml von Magento_Elasticsearch als virtueller Typ zusammengesetzt, der wiederum eine Liste von FieldProvider-Klassen zusammenfuehrt. Jeder FieldProvider ist fuer eine bestimmte Kategorie von Attributen zustaendig: einer fuer statische Attribute wie sku und price, einer fuer dynamische EAV-Attribute, ein weiterer fuer System-Felder wie visibility und status.

Diese Struktur erlaubt zwei grundsaetzliche Erweiterungswege fuer ein Custom-Attribute-Mapping. Der erste ist additiv: ein zusaetzlicher FieldProvider wird der bestehenden Liste hinzugefuegt und liefert Feldnamen und -typen fuer Attribute, die die Standardprovider nicht abdecken. Der zweite ist dekorativ: ein Plugin auf einen bestehenden FieldMapper aendert das Verhalten fuer einzelne, bereits abgedeckte Attribute, etwa um einen abweichenden Feldnamen oder Typ zu erzwingen.

<!-- app/code/Mironsoft/SearchExtension/etc/di.xml -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <!-- Register a custom field provider for attributes with special mapping needs -->
    <type name="Magento\Elasticsearch\Model\Adapter\FieldMapper\Product\FieldProviderInterface">
        <plugin name="mironsoft_custom_field_provider"
                type="Mironsoft\SearchExtension\Plugin\CustomFieldProviderPlugin"
                sortOrder="20"/>
    </type>

    <!-- Virtual type: extend the field type resolver array with a custom entry -->
    <virtualType name="Magento\Elasticsearch\Model\Adapter\FieldType\Text" shared="false"/>
    <type name="Magento\Elasticsearch\Model\Adapter\FieldMapper\Product\FieldProvider\CustomAttribute">
        <arguments>
            <argument name="fieldTypeConverter" xsi:type="object">
                Mironsoft\SearchExtension\Model\Adapter\FieldType\CustomTypeResolver
            </argument>
        </arguments>
    </type>
</config>

3. searchable, filterable, used_for_sort_by im Detail

Drei Attributflags steuern beim Custom-Attribute-Mapping massgeblich, wie ein Attribut im Elasticsearch-Index behandelt wird. is_searchable nimmt das Attribut in die Volltextsuche auf: Sein Wert fliesst in die kombinierte multi_match-Query ein, die beim Absetzen einer Suchanfrage ueber mehrere Felder gleichzeitig sucht. is_filterable beziehungsweise is_filterable_in_search macht das Attribut fuer die Layered Navigation nutzbar und beeinflusst, ob ein keyword-Sub-Feld fuer exakte Aggregationen angelegt wird.

Das dritte Flag, used_for_sort_by, entscheidet, ob ein Attribut als Sortierkriterium in der Produktliste zur Verfuegung steht. Fuer text-Felder ist Sortierung nur ueber das zusaetzliche keyword-Sub-Feld sinnvoll moeglich, weshalb Magento bei aktivem used_for_sort_by-Flag automatisch dieses Sub-Feld anlegt. Wer ein Custom-Attribute-Mapping fuer ein Attribut mit allen drei Flags plant, muss diese Kombination bewusst im Feldtyp abbilden, meist als text-Feld mit zusaetzlichem fields.keyword-Sub-Feld fuer Filter und Sortierung.

{
  "properties": {
    "material": {
      "type": "text",
      "fields": {
        "keyword": { "type": "keyword", "ignore_above": 256 }
      }
    }
  }
}

4. Field-Type-Ableitung: vom EAV-Backend-Type zum ES-Typ

Ohne explizite Steuerung leitet Magento den Elasticsearch-Feldtyp beim Custom-Attribute-Mapping aus dem EAV-Backend-Type des Attributs ab. Diese Ableitung geschieht in einer Reihe von FieldType-Klassen, die je Backend-Type registriert sind: varchar und text werden zu text, int zu integer, decimal zu float, datetime zu date. Diese Standardableitung passt fuer die meisten Faelle, versagt aber bei Attributen mit besonderen Anforderungen, etwa einem numerischen Attribut, das als Text gespeichert wird, weil fuehrende Nullen erhalten bleiben sollen.

Fuer solche Faelle erlaubt das Custom-Attribute-Mapping, einen eigenen Feldtyp-Resolver zu registrieren, der fuer bestimmte Attributcodes eine abweichende Typzuordnung liefert. Diese Klasse implementiert dasselbe Interface wie die Standard-Resolver und wird ueber di.xml vor die Standardkette gesetzt, sodass sie fuer die betroffenen Attribute greift, bevor die generische Backend-Type-Ableitung ueberhaupt zum Zug kommt.

5. Eigenen FieldProvider fuer ein Custom-Attribut implementieren

Ein eigener FieldProvider ist der sauberste Weg, ein Custom-Attribute-Mapping zu implementieren, das ueber einfache Typ-Overrides hinausgeht. Die Klasse muss FieldProviderInterface implementieren und liefert eine Liste von Feldern mit Name, Typ und weiteren Elasticsearch-Mapping-Parametern wie analyzer oder copy_to. Diese Felder werden anschliessend mit den Feldern der Standard-Provider zusammengefuehrt, bevor das vollstaendige Mapping fuer den PUT-Request an Elasticsearch generiert wird.

<?php
declare(strict_types=1);

namespace Mironsoft\SearchExtension\Model\Adapter\FieldMapper;

use Magento\Elasticsearch\Model\Adapter\FieldMapper\Product\FieldProviderInterface;
use Magento\Eav\Model\Config as EavConfig;

/**
 * Provides an explicit Elasticsearch field definition for the custom
 * "warranty_months" attribute, mapped as an integer with a fixed name.
 */
class WarrantyFieldProvider implements FieldProviderInterface
{
    private const ATTRIBUTE_CODE = 'warranty_months';

    /**
     * @param EavConfig $eavConfig
     */
    public function __construct(private readonly EavConfig $eavConfig)
    {
    }

    /**
     * Returns the custom field definition for the warranty attribute.
     *
     * @param array $context
     * @return array
     */
    public function getFields(array $context = []): array
    {
        $attribute = $this->eavConfig->getAttribute('catalog_product', self::ATTRIBUTE_CODE);
        if (!$attribute->getAttributeId()) {
            return [];
        }

        return [
            self::ATTRIBUTE_CODE => [
                'type' => 'integer',
            ],
        ];
    }
}

6. Mapping-Konflikte erkennen und vermeiden

Ein haeufiger Fehler bei einem eigenen Custom-Attribute-Mapping ist der Konflikt zwischen zwei FieldProvidern, die fuer denselben Attributcode unterschiedliche Feldtypen liefern. Elasticsearch akzeptiert pro Feldname genau eine Typdefinition; wird derselbe Feldname mit unterschiedlichen Typen aus zwei Quellen zusammengefuehrt, entscheidet die Reihenfolge in der Provider-Liste, welcher Typ tatsaechlich verwendet wird, ohne dass ein sichtbarer Fehler auftritt. Das fuehrt zu schwer nachvollziehbaren Bugs, bei denen ein Filter auf einmal nicht mehr funktioniert, nachdem ein zweites Modul denselben Attributcode gemappt hat.

Der zuverlaessige Weg, solche Konflikte zu vermeiden, ist ein konsistentes Namensschema fuer Custom-Attribute und eine explizite Pruefung des generierten Mappings nach jeder Aenderung. Ein Blick in GET /magento2_product_1_v1/_mapping/field/warranty_months zeigt sofort, welcher Typ tatsaechlich aktiv ist, unabhaengig davon, welche Provider-Reihenfolge im Hintergrund gegriffen hat.

7. Reindex-Strategie nach Mapping-Aenderungen

Jede Aenderung am Custom-Attribute-Mapping, die einen bestehenden Feldtyp betrifft, erfordert einen vollstaendigen Reindex, weil Elasticsearch Feldtypen nachtraeglich nicht aendern kann. Neue Felder fuer neue Attribute lassen sich dagegen additiv ergaenzen, ohne den bestehenden Index neu aufzubauen, solange der Feldname vorher nicht existiert hat. Diese Unterscheidung ist beim Rollout eines Custom-Attribute-Mappings entscheidend fuer die Planung: Ein reines Hinzufuegen ist risikoarm, eine Typaenderung an einem bestehenden Feld erfordert einen kontrollierten Reindex mit Alias-Swap.

In der Praxis empfiehlt sich, neue FieldProvider zunaechst in einer Staging-Umgebung mit einem frischen Index zu testen, bevor das Custom-Attribute-Mapping in Produktion ausgerollt wird. So laesst sich das generierte Mapping vollstaendig validieren, bevor ein produktiver Full-Reindex angestossen wird, der bei grossen Katalogen mehrere Stunden dauern kann.

8. Testen: Mapping inspizieren und validieren

Vor jedem produktiven Rollout eines Custom-Attribute-Mappings lohnt sich ein systematischer Test in einer isolierten Umgebung. Der erste Schritt ist, das generierte Mapping direkt ueber die Elasticsearch-API abzufragen und mit der erwarteten Struktur zu vergleichen. Der zweite Schritt ist ein Testdokument mit realistischen Werten, das ueber die Bulk-API eingespielt und anschliessend ueber eine gezielte Query auf das neue Feld geprueft wird.

# Verify the generated mapping for a custom field after reindex
curl -s -X GET "https://localhost:9200/magento2_product_1_v1/_mapping/field/warranty_months?pretty"

# Test filtering on the new field with a real query
curl -s -X GET "https://localhost:9200/magento2_product_1_v1/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{"query": {"range": {"warranty_months": {"gte": 24}}}}'

9. Praxisbeispiel: Boolean-Attribut mit eigenem Analyzer

Ein konkretes Beispiel fuer erweitertes Custom-Attribute-Mapping ist ein Boolean-Attribut "nachhaltig_produziert", das sowohl als Filter in der Layered Navigation als auch mit einem eigenen deutschen Synonym-Analyzer fuer verwandte Suchbegriffe wie "oeko" oder "umweltfreundlich" durchsuchbar sein soll. Ein reines boolean-Feld deckt den Filter-Anwendungsfall ab, nicht aber die Synonym-Suche, weshalb hier zwei Felder kombiniert werden: ein boolean-Feld fuer den exakten Filter und ein zusaetzliches text-Feld mit Custom-Analyzer, das nur bei "true" befuellt wird und die Synonym-Suchbegriffe enthaelt.

Diese Kombination zeigt, dass Custom-Attribute-Mapping nicht immer eine Eins-zu-eins-Beziehung zwischen EAV-Attribut und Elasticsearch-Feld bedeutet. Ein einzelnes Attribut kann durchaus mehrere Felder im Index erzeugen, wenn unterschiedliche Anwendungsfaelle wie exakter Filter und erweiterte Volltextsuche gleichzeitig bedient werden sollen. Der FieldProvider fuer dieses Attribut liefert entsprechend zwei Eintraege statt eines einzigen.

10. Zusammenfassung

Ein durchdachtes Custom-Attribute-Mapping in Magento geht ueber das reine Setzen von is_searchable und is_filterable hinaus. Erst eigene FieldProvider- und FieldMapper-Klassen, registriert ueber di.xml, erlauben volle Kontrolle darueber, unter welchem Namen, mit welchem Feldtyp und mit welchem Analyzer ein Attribut im Elasticsearch-Index landet. Diese Kontrolle wird besonders wichtig bei Attributen mit besonderen Anforderungen wie Synonym-Suche, abweichenden numerischen Formaten oder mehreren gleichzeitigen Anwendungsfaellen.

Wer ein Custom-Attribute-Mapping plant, sollte Mapping-Konflikte zwischen Modulen aktiv pruefen, Typaenderungen an bestehenden Feldern von additiven Erweiterungen unterscheiden und jede Aenderung vor dem produktiven Rollout in einer isolierten Umgebung validieren. Diese Disziplin verhindert die typischen, schwer nachvollziehbaren Fehler, bei denen ein Filter oder eine Suche nach einem scheinbar unabhaengigen Modul-Update ploetzlich anders funktioniert.

11. FAQ: Custom-Attribute-Mapping in Magento