Fulltext pro e-shop entity (produkty, značky, kategorie, skupiny)

Fulltext pro e-shop entity (produkty, značky, kategorie, skupiny)

Tento dokument shrnuje možnosti nastavení fulltextu pro e‑shop entity.

Zkopírovat odkaz na sekciCo fulltext dělá

  • Vyhledává v publikovaných e‑shop datech: produkty, značky, kategorie a skupiny.
  • Standardně indexuje základní pole (název, popisy, katalogové číslo, EAN apod.), ale řídí se konfigurací.
  • Podporuje vícejazyčné a víceregionální e-shopy (indexace podle regionů).
  • Výsledky se zobrazují v našeptávači i na výsledkové stránce, podporují stránkování, filtrování i třídění.
  • Výchozí minimum délky hledaného výrazu je 3 znaky (pokud je kratší, dotaz se neprovede).

Zkopírovat odkaz na sekciKde se fulltext nastavuje

  1. Globální fulltext modul
    Konfigurace v edee/config/module-fulltext/module-fulltext.xml definuje nastavení modulu. Podrobnosti zde.

  2. Konfigurace e‑shop entit
    Konfigurace v edee/config/module-edeeshop/features/catalog/*.xml (product.xml, brand.xml, category.xml, group.xml):

  • fulltextConfig/providers = definice zdrojů dat (co se indexuje),
  • fulltextConfig/sections = definice sekcí (kde a pro jaké regiony se indexuje).
  1. Frontend API
    Vyhledávání je dostupné přes FulltextController: GET /api/eshop/{catalogCode}/fulltext (více kapitola API pro FE).

Zkopírovat odkaz na sekciMinimální postup nastavení

  1. Nastav fulltext modul

Z pohledu e-shopu není potřeba nic měnit, ale modul musí být zapnutý a správně nastavený.

  1. Definuj providery pro entity
    V edee/config/module-edeeshop/features/catalog/*.xml nastav fulltextConfig/providers/provider. Důležité body:
  • type musí být unikátní napříč všemi providery v aplikaci (např. products, brands).
  • builder/indexedProperties určuje, co se indexuje.
  • builder/variables a builder/dataList ukládají data do výsledků (např. pro grouping a filtrování).
  • query může omezit výběr entit (např. jen aktivní).
  • visibleForStockOnly (produkty) omezí indexaci na položky dostupné na skladu.
  1. Vytvoř sekce (sections)
    fulltextConfig/sections/section určuje fragment, providers, regions a sitemapId.
    Pokud je sections prázdné, entity se neindexují.

Pozn.: název sekce se skládá jako catalog_region_fragment (např. demo_czcsczk_products).
fragment se pak používá v API parametru sectionFragment. Seznam všech sekcí je dostupný v admin modulu.

Podrobnosti o konfiguraci fulltextConfig/providers/provider a fulltextConfig/sections/section k jednotlivým entitám:

  1. Spusť indexaci
    Fulltext hledá až po úspěšné indexaci (viz "Úlohy na pozadí" a skupina "Fulltextové vyhledávání").

Zkopírovat odkaz na sekciUkázková konfigurace

Níže je zkrácený výpis z demo konfigurace.

Zkopírovat odkaz na sekciProdukty

xml
1 <fulltextConfig>2  <providers>3    <provider>4      <type>products</type>5      <query>6        <referencedEntities>7          <!-- Chceme indexovat i značku produktu, musíme ji načíst -->8          <referencedEntity>brand</referencedEntity>9        </referencedEntities>10      </query>11      <visibleForStockOnly>true</visibleForStockOnly>12      <builder>13        <gallery>hlavni-motiv</gallery>14        <indexedProperties>15          <indexedProperty>name</indexedProperty>16          <indexedProperty>titleOrName</indexedProperty>17          <indexedProperty>description</indexedProperty>18          <indexedProperty>descriptionShort</indexedProperty>19          <indexedProperty>getLocalizedTextByCode('metaDescription')</indexedProperty>20          <indexedProperty>catalogNumber</indexedProperty>21          <indexedProperty>ean</indexedProperty>22          <indexedProperty>brand?.brand?.name</indexedProperty>23        </indexedProperties>24        <variantId>eshop-product-detail-microdata-1x1</variantId>25        <variables>26          <variable>productType.name</variable>27        </variables>28      </builder>29    </provider>30  </providers>31  <sections>32    <section>33      <fragment>products</fragment>34      <providers>35        <provider>products</provider>36      </providers>37      <regions>38        <region>39          <country>cz</country>40          <locale>cs</locale>41          <currency>CZK</currency>42        </region>43      </regions>44      <sitemapId>csDemoSitemap</sitemapId>45      <fieldAnalyzers>46        <fieldAnalyzer>47          <field>title</field>48          <analyzer>czech-edee-summon</analyzer>49        </fieldAnalyzer>50        <fieldAnalyzer>51          <field>content</field>52          <analyzer>czech-edee</analyzer>53        </fieldAnalyzer>54      </fieldAnalyzers>55    </section>56  </sections>57</fulltextConfig>

Zkopírovat odkaz na sekciZnačky / kategorie / skupiny

xml
1 <fulltextConfig>2  <providers>3    <provider>4      <type>brands</type>5      <builder>6        <gallery>hlavni-motiv</gallery>7        <indexedProperties>8          <indexedProperty>name</indexedProperty>9          <indexedProperty>titleOrName</indexedProperty>10          <indexedProperty>description</indexedProperty>11          <indexedProperty>descriptionShort</indexedProperty>12          <indexedProperty>getLocalizedTextByCode('metaDescription')</indexedProperty>13        </indexedProperties>14      </builder>15    </provider>16  </providers>17  <sections>18    <section>19      <fragment>brands</fragment>20      <providers>21        <provider>brands</provider>22      </providers>23      <regions>24        <region>25          <country>cz</country>26          <locale>cs</locale>27          <currency>CZK</currency>28        </region>29      </regions>30      <sitemapId>csDemoSitemap</sitemapId>31      <fieldAnalyzers>32        <fieldAnalyzer>33          <field>title</field>34          <analyzer>czech-edee-summon</analyzer>35        </fieldAnalyzer>36        <fieldAnalyzer>37          <field>content</field>38          <analyzer>czech-edee</analyzer>39        </fieldAnalyzer>40      </fieldAnalyzers>41    </section>42  </sections>43</fulltextConfig>

Stejný vzor platí pro categories a groups (liší se type/fragment).

Zkopírovat odkaz na sekciJak fulltext ladit

Zkopírovat odkaz na sekci1) Analyzátory (sekce a pole)

  • section/analyzer nastaví výchozí analyzátor pro sekci.
  • section/fieldAnalyzers/fieldAnalyzer umožní rozlišit analyzátor pro title a content.
  • Doporučení: agresivnější analyzátor pro title (czech-edee-summon) a standardní pro content (czech-edee).

Podporované analyzátory: czech-edee, czech-edee-summon, universal, english, ... (viz dokumentace).

Zkopírovat odkaz na sekci2) Profily vyhledávání (Search Profiles)

V module-fulltext.xml lze definovat profily:

xml
1 <profile name="defaultProfile">2  <param name="titleBoost" value="3"/>3  <param name="promoItems" value="3"/>4</profile>

Profil se předává query parametrem profile do FulltextController.
Pokud profile není uveden, použije se fallback logika popsaná níže v sekci API pro FE.

Zkopírovat odkaz na sekci3) Indexace identifikátorů (EAN, katalogové číslo)

Pro ean a catalogNumber je použita strategie indexace s ořezáváním zprava (RecursiveRightTrimWithDigitsIndexBuilder), která umožní hledat i části kódu.

Konkrétní chování RecursiveRightTrimWithDigitsIndexBuilder:

  • generuje tokeny postupným ořezáváním zprava,
  • navíc extrahuje číslice a ty indexuje stejným způsobem,
  • výchozí minimální délka tokenu je 3.

Příklad pro ABC12345:

  • textová část: ABC12345, ABC1234, ABC123, ...
  • čísla: 12345, 1234, 123, ...

Zkopírovat odkaz na sekciVlastní index buildery

Pokud chcete jinou strategii pro další atributy, použijte vlastní implementaci IndexBuilder (com.fg.cps.eshop.catalog.cps.fulltext.service.builder.IndexBuilder) a zaregistrujte ji v AbstractFulltextResourceBuilder.registerIndexBuilder.

Kroky:

  1. Implementujte IndexBuilder – např. ořezávání zleva, normalizace prefixů, custom tokenizace:
java
1 public class MySkuIndexBuilder implements IndexBuilder {2    @Override3    public void indexString(IndexBuilderContext context, @Nullable String value) {4        if (value == null) {5            return;6        }7        context.indexValue(value.toUpperCase(Locale.ROOT));8        // případně další tokeny...9    }10}
  1. Zaregistrujte builder pro konkrétní atribut
    Klíč musí odpovídat přesně výrazu v indexedProperties (např. catalogNumber, ean, nebo i složitější SpEL jako brand?.brand?.name).
java
1 public class CustomProductResourceBuilder extends ProductResourceBuilder {2    public CustomProductResourceBuilder(/* dependencies */) {3        super(/* dependencies */);4        registerIndexBuilder("catalogNumber", new MySkuIndexBuilder());5        registerIndexBuilder("ean", RecursiveRightTrimWithDigitsIndexBuilder.INSTANCE);6    }7}
  1. Zajistěte použití builderu v projektu
    V FulltextResourceBuilderProvider lze přeregistrovat builder pro entitu:
java
1 builderProvider.registerFulltextResourceBuilder(CatalogEntityType.PRODUCT, customProductResourceBuilder);

Zkopírovat odkaz na sekciAPI pro FE (FulltextController)

Endpoint:

1 GET /api/eshop/{catalogCode}/fulltext

Parametry:

  • catalogRegion (např. cz_czk)
  • sectionFragment (např. products, brands, categories, groups)
  • query (hledaný výraz)
  • pageSize, pageNumber
  • variables (např. MASTER OR BASIC OR SET)
  • profile (volba search profilu)
  • promoItemCount (max promo výsledků)
  • fulltextGroupResultMapperName (volitelný mapper pro groupování)

Výsledky jsou seskupené (master + varianty). Pokud je nalezen master, varianty se ve výsledku nevypisují samostatně.

Zkopírovat odkaz na sekciParametr profile

Umožňuje klientovi zvolit konkrétní vyhledávací profil (Search Profile) definovaný v konfiguraci fulltextového modulu.

Pokud je parametr profile zadán, FulltextController jej předá do SearchParams. Na základě zvoleného profilu se následně aplikují příslušná nastavení, jako je například titleBoost.

Pokud profile není zadán (výchozí stav), použije se „ad-hoc“ logika, která zvýhodňuje titulek pomocí parametru titleBoost.

Dále platí, že pokud není profile definován, předává se hledaná hodnota také do searchParams.term. To zajistí, že se v polích title i content bude hledat přesně zadaný výraz bez vlivu analyzéru. Při přesné shodě tak fulltext najde záznam i v případech, kdy by to úprava slova analyzérem neumožnila.

Podrobnější popis dalších parametrů zde.

Zkopírovat odkaz na sekciDiagnostika a ladění

Pro ladění analyzátorů a tokenizace lze použít diagnostické nástroje v sekci "Nastavení"/"Fulltext" v administraci.

Zkopírovat odkaz na sekciSouvisející dokumentace