Magento i OpenSearch: jak działa indeks katalogu i dlaczego nie Elasticsearch

Katalog produktów sklepu jest w MySQL, nie w OpenSearch

Produkty, warianty, kategorie, ceny, stany magazynowe i konfiguracja sklepu należą do relacyjnej bazy Magento - w instalacji laboratoryjnej jest to MySQL 8.4.11. Model katalogu korzysta między innymi z EAV (Entity-Attribute-Value, czyli encja-atrybut-wartość): produkt jest encją, „kolor” lub „rozmiar” jest atrybutem, a „granatowy” albo „M” jego wartością. Ten elastyczny model pozwala różnym typom produktów mieć różne cechy, dlatego dane produktu są rozłożone na wiele rekordów, a nie zawsze mieszczą się w jednym wierszu.

OpenSearch nie jest miejscem ręcznego utrzymywania katalogu produktów sklepu. Magento buduje w nim odtwarzalny indeks dokumentów: wybiera dane produktów potrzebne do wyszukania i filtrowania, przygotowuje je dla poszczególnych widoków sklepu i wysyła jako dokumenty JSON. Indeks nie jest kopią wszystkich tabel - nie przechowuje na przykład historii zamówień ani pełnego modelu administracyjnego Magento. Oficjalna dokumentacja indeksowania Adobe opisuje indeks jako reprezentację danych źródłowych zoptymalizowaną pod odczyt, którą można przebudować.

To rozdzielenie ma praktyczny skutek: awaria indeksu wyszukiwania jest problemem dla wyszukiwarki i filtrów, ale nie oznacza utraty katalogu. Dane poprawiamy w Magento, a indeks naprawiamy przez indexer Magento. Nie importujemy do OpenSearch zrzutu SQL i nie zasilamy go ręcznie przez curl.

Zmiana nazwy produktu: od panelu Magento do wyniku wyszukiwania

Weźmy produkt o SKU KOSZ-LEN-GR-M. W panelu Magento jego nazwa zmienia się z „Koszula lniana czarna” na „Koszula lniana granatowa”. Nazwa jest atrybutem oznaczonym jako używany w wyszukiwaniu. Po zapisie nowy tekst trafia najpierw do MySQL; wynik w sklepie nie bierze się z osobnego formularza ani z ręcznego importu do OpenSearch.

panel administracyjny / import / API
                 │
                 ▼
       MySQL: katalog produktów Magento (źródło prawdy)
                 │
                 ▼
     MView i cron albo aktualizacja przy zapisie
                 │
                 ▼
     indexer catalogsearch_fulltext Magento
                 │
                 ▼
       dokument produktu w OpenSearch
                 │
                 ▼
  zapytanie „koszula granatowa” w sklepie

W trybie Update on Save Magento aktualizuje indeks w trakcie zapisu. W trybie Update by Schedule - zwykle właściwszym przy większym katalogu, imporcie i ruchu klientów - mechanizm MView zapisuje zmianę w tabeli zmian, a cron uruchamia indeksator w tle. Adobe zaleca ten drugi tryb dla wydajności, ponieważ pozwala odkładać pracę indeksowania i wykonywać ją partiami. Zależność od crona jest realna: bez poprawnie działającego crona nowy produkt może być widoczny w panelu, ale jeszcze nie znaleźć się w wynikach wyszukiwania.

Nie każdy atrybut produktu staje się tekstem do przeszukania. O tym decyduje konfiguracja atrybutu, w szczególności Use in Search. Waga wyszukiwania od 1 do 10 wpływa na ranking dopasowania. Dokładne zachowanie wyszukiwania po fragmencie zależy od pola i konfiguracji; domyślnie Magento obsługuje prefiksowe wyszukiwanie części frazy dla name i sku, ale nie należy zakładać automatycznego wyszukiwania po końcówce SKU. Te zasady opisuje dokumentacja wyników wyszukiwania Adobe.

Pełna reindeksacja i aktualizacja przyrostowa to różne operacje

Za indeks katalogu odpowiada indexer o identyfikatorze catalogsearch_fulltext. Pełne przeliczenie czyta katalog z MySQL i buduje komplet dokumentów. Jest potrzebne po pierwszej konfiguracji silnika, po zmianie silnika wyszukiwania, po niektórych zmianach struktury atrybutów oraz po zaplanowanej naprawie indeksu. Nie jest to polecenie do bezrefleksyjnego uruchamiania po każdej pojedynczej zmianie produktu.

sudo -u "$MAGENTO_OWNER" bin/magento indexer:reindex catalogsearch_fulltext

Polecenie należy uruchamiać jako właściciel plików Magento; w naszym labie jest to użytkownik magento, a aplikacja leży w /srv/magento. Przy dużym katalogu reindeksacja obciąża MySQL, PHP i OpenSearch, więc na produkcji planujemy ją świadomie. Magento wysyła dokumenty partiami; kod taga 2.4.9 używa nazw wersjonowanych indeksów oraz aliasu, dzięki czemu kompletnie zbudowany indeks może zastąpić poprzedni bez udostępniania klientom jego niedokończonej wersji. To także powód, aby nie usuwać ręcznie indeksów widocznych w OpenSearch tylko dlatego, że ich nazwa wygląda na starą.

Przy pracy według harmonogramu pełna reindeksacja pozostaje operacją wyjątkową. Zmiana produktu, import lub usunięcie produktu zostawiają ślad dla indexera, a zadanie crona przenosi wynik do indeksu. Adobe opisuje obydwa tryby i wskazuje, że triggery bazodanowe są zakładane w trybie harmonogramu; szczegóły oraz polecenia zmiany trybu znajdują się w dokumentacji zarządzania indexerami.

Co OpenSearch robi z danymi produktu

Po stronie OpenSearch produkt jest dokumentem, a nie wierszem SQL. Uproszczony dokument dla naszego przykładu można wyobrazić sobie tak:

{
  "entity_id": 214,
  "sku": "KOSZ-LEN-GR-M",
  "name": "Koszula lniana granatowa",
  "material": "len"
}

To schemat wyjaśniający, nie surowy zrzut konkretnego indeksu Magento. Rzeczywiste pola i ich typy zależą od konfiguracji sklepu, atrybutów i modułów. Magento tworzy mapping, czyli definicję sposobu przechowywania i indeksowania pól. OpenSearch rozróżnia między innymi pola tekstowe, dokładne wartości typu keyword, liczby i daty.

Dla tekstu silnik uruchamia analizator: dzieli nazwę na terminy, normalizuje je, a następnie zapisuje indeks odwrócony. Zamiast przeglądać opisy wszystkich produktów dla frazy „koszula granatowa”, ma w praktyce listę dokumentów zawierających termin „koszula” i listę dokumentów zawierających termin „granatowa”. Łączy je, wylicza trafność i zwraca identyfikatory pasujących produktów. Zapytanie przechodzi podobną analizę. Mechanikę analizatorów i zapytań pełnotekstowych opisuje dokumentacja OpenSearch Analyzers oraz full-text queries.

Magento używa zwróconych identyfikatorów i danych katalogowych, aby zbudować stronę wyników. Dzięki temu wyszukiwarka nie zastępuje modelu relacyjnego Magento, lecz wykonuje pracę, do której indeks pełnotekstowy jest stworzony: dopasowanie tekstu, ranking oraz - zależnie od konfiguracji - agregacje potrzebne do filtrów warstwowych.

Najpierw sprawdzamy indexer, potem przebudowujemy indeks

Diagnozę zaczynamy od odczytu stanu. Poniższe polecenia nie zmieniają danych:

sudo -u "$MAGENTO_OWNER" bin/magento indexer:status catalogsearch_fulltext
sudo -u "$MAGENTO_OWNER" bin/magento indexer:show-mode catalogsearch_fulltext
sudo -u "$MAGENTO_OWNER" bin/magento config:show catalog/search/engine

Interesują nas trzy odpowiedzi: czy indeks jest poprawny czy wymaga reindeksacji, czy aktualizuje się przy zapisie czy według harmonogramu oraz czy Magento rzeczywiście ma ustawione opensearch. Wynik Reindex Required nie wyjaśnia jeszcze przyczyny; przy trybie harmonogramu sprawdzamy przede wszystkim cron, a po błędzie połączenia - konfigurację silnika i jego logi.

Na hoście laboratoryjnym OpenSearch nasłuchuje wyłącznie na loopbackie. Jego odpowiedź i nazwy aliasów można wtedy sprawdzić bez modyfikowania indeksu:

curl --fail --silent --show-error http://127.0.0.1:9200/
curl --fail --silent --show-error http://127.0.0.1:9200/_cat/aliases?v

Pierwsze zapytanie potwierdza działanie usługi i wersję. Drugie pomaga zobaczyć aliasy, których używa Magento; liczba widocznych indeksów lub dokumentów nie musi odpowiadać prostemu „liczba produktów”, ponieważ występują widoki sklepu, aliasy i wersje indeksu. W środowisku produkcyjnym adres, TLS i uwierzytelnianie muszą odpowiadać konfiguracji tej instancji - portu 9200 nie wystawiamy publicznie tylko po to, aby wykonać takie sprawdzenie.

Produkt jest w panelu, ale nie ma go w wyszukiwarce

Najczęstsza pułapka polega na uruchomieniu pełnego reindeksowania zanim wiadomo, czego brakuje. Lepiej przejść od produktu do mechanizmu aktualizacji. Najpierw sprawdzamy, czy produkt jest włączony, widoczny w katalogu, przypisany do właściwej witryny i widoku sklepu oraz czy atrybut, po którym ma być znajdowany, ma włączone użycie w wyszukiwaniu. Dopiero potem sprawdzamy catalogsearch_fulltext.

Jeżeli indexer działa według harmonogramu, kontrolujemy wpis crona i błędy. Magento zapisuje informacje o zadaniach w var/log/cron.log, wyjątki w var/log/exception.log, a historię harmonogramu także w tabeli cron_schedule. Oficjalna instrukcja konfiguracji crona podkreśla, że poprawnie działający cron jest wymagany między innymi dla reindeksacji.

Gdy cron jest zdrowy, Magento ma silnik opensearch, a indexer nadal wymaga przeliczenia, uruchamiamy reindeks tego jednego indexera i po jego zakończeniu wyszukujemy świeżo zmienioną frazę. Nie łączymy zwykłego reindeksowania z automatycznym czyszczeniem wszystkich cache. Adobe wymaga odświeżenia page cache po zmianie konfiguracji silnika, ale są to dwie osobne operacje.

Dlaczego dla Magento 2.4.9 używamy OpenSearch, a nie Elasticsearch

Nie dlatego, że Elasticsearch jest z definicji zły. Ogólna dokumentacja Adobe nadal mówi, że od Commerce 2.4.4 katalog może korzystać z Elasticsearch albo OpenSearch. Taka informacja nie wystarcza jednak do wyboru wersji w nowej instalacji. Decyduje macierz dla konkretnego wydania Magento.

W macierzy wymagań systemowych Adobe, odczytanej 25 września 2026 r., dla Magento/Adobe Commerce 2.4.9 on-premises wskazano OpenSearch 3; Elasticsearch nie występuje w tym wierszu. Tymczasem bieżące wydanie Elasticsearch producenta to 9.5.4 z 15 września 2026 r. Sam fakt, że jest nowsze, nie czyni go zgodnym z integracją Magento. Dlatego dla świeżego Magento Open Source 2.4.9 wybieramy OpenSearch 3.8.0, a nie przypadkową wersję Elasticsearch.

OpenSearch i Elasticsearch mają wspólną historię, ale są dziś odrębnymi projektami; podobne API nie daje swobody podmieniania ich wersji. Kwestie licencyjne opisują FAQ OpenSearch i FAQ Elastic, lecz dla tej instalacji decydująca jest zgodność OpenSearch 3 z Magento 2.4.9.

Istniejąca, starsza instalacja Magento może mieć inne wymagania i inną, wspieraną wersję Elasticsearch. Nie przenosimy jednak tej decyzji automatycznie do Magento 2.4.9. Przed aktualizacją zawsze sprawdzamy macierz właściwą dla docelowego patch release, a nie ogólny poradnik i nie sam numer najnowszego pakietu.

Co sprawdzamy po zmianie katalogu

1. Produkt jest włączony, widoczny i przypisany do właściwego widoku sklepu.
2. Atrybut, po którym wyszukujemy, ma odpowiednią konfigurację Use in Search i wagę.
3. catalogsearch_fulltext ma właściwy tryb oraz stan; przy harmonogramie działa cron.
4. Magento wskazuje opensearch, a usługa odpowiada z poprawną wersją.
5. Po planowanej reindeksacji wynik wyszukiwania i filtr odpowiadają zmianie produktu.

W ten sposób rozdzielamy trzy różne problemy: dane produktu w Magento, kolejkę/indexer i sam silnik wyszukiwania. Właśnie to rozdzielenie sprawia, że OpenSearch daje Magento szybkie wyszukiwanie bez zamieniania go w drugą główną bazę danych.