Topdata Topdata Docs

TopdataEnhancedSearchSW6

Topdata Enhanced Search SW6 User Manual

Overview

Topdata Enhanced Search SW6 replaces the plain storefront search result list with a search overlay that answers while the customer types. The overlay groups the matches into products, categories, manufacturers, consumable devices and curated search suggestions, and shows how many products each suggestion would find.

On top of that it adds the tooling a shop needs to keep its search quality high: it logs what customers actually search for, mines recurring phrases out of your product titles, proposes synonyms for terms that return nothing, and lets you approve or reject those proposals in the administration.

Key Features

  • Search overlay with configurable sections: products, categories, manufacturers, consumable devices, search suggestions and recent searches
  • Search suggestions mined from product titles — phrases shared by several products become suggestions, each with a cached product count
  • Synonyms with per-rule boost levels, editable in the administration or via text/CSV import and export
  • Synonym suggestions generated from your own search analytics: title-mined phrases, manufacturer-number prefix families (e.g. TN 247 → TN-247), an LLM strategy and a thesaurus strategy
  • Optional AI banding (Jev) to pre-classify suggestions as approved, uncertain or discarded — in a calibration mode first, active only when you switch it on
  • Search analytics per storefront language, with a search log, hourly statistics, noise detection and CSV export
  • Search exclusion by category, plus a filter map that keeps specific products out of the results for a given search term
  • Themeable overlay: all colours are CSS custom properties, so a theme can restyle the overlay without touching the plugin

Getting Started

  1. Follow the Installation Guide and rebuild the search index.
  2. Adjust the overlay in the Settings Guide.
  3. Learn how customers use the search and how you maintain synonyms in the Usage Guide.
  4. If something does not behave as expected, check the FAQ & Troubleshooting.

Support

For additional support, please contact our technical support team or visit our support portal.

Topdata Enhanced Search SW6 Installation Guide

System Requirements

  • Shopware 6.7 (with Elasticsearch/OpenSearch, as required by Shopware itself)
  • PHP version as required by Shopware 6.7, plus the ext-pdo extension
  • The plugins topdata/topdata-foundation-sw6 (>= 1.6.0) and topdata/topdata-top-finder-pro (>= 8.4.0)

Installation Steps

1. Install via Composer

composer require topdata/enhanced-search-sw6

The required Topdata plugins are pulled in automatically.

2. Activate the Plugin

Option A: Using the Shopware Admin Panel

  1. Log in to your Shopware admin panel.
  2. Go to Extensions > My extensions.
  3. Find “Topdata Enhanced Search SW6” in the list.
  4. Click Activate.

Option B: Using the Command Line

bin/console plugin:install --activate TopdataEnhancedSearchSW6

3. Rebuild the Search Index

The plugin extends the Shopware product index definition, so a full index rebuild is required after the installation:

bin/console es:index

This can take several minutes on a large catalogue. Do not skip it — without a rebuild the plugin’s matching rules are not active.

4. Clear Cache

bin/console cache:clear

Verification

  • Open the storefront and type at least two letters into the search field: the search overlay opens below the search field with at least one section.
  • Open the administration under Topdata Enhanced Search: the pages Synonyms, Search Suggestions, Search Log and Search Statistics are available.

Optional: AI Features

The strategies that use a language model and the AI banding of synonym suggestions require the additional plugin topdata/llm-connect-sw6 with an API credential stored there. The status is shown in the plugin settings (Synonym Suggester > LLM provider status). Without that plugin the LLM-based strategies are skipped and everything else keeps working.

Troubleshooting

The search overlay does not appear

  • Confirm the plugin is active: bin/console plugin:list.
  • Rebuild the index: bin/console es:index.
  • Check that no theme removes the original search form; the overlay attaches to the storefront search field.

Many search terms return no results right after installation

Products that were only recently activated are missing from the index until it is rebuilt. Run bin/console es:index.

Installation fails with a missing table

Migrations create the plugin’s own tables (tdes_*). Never remove them manually. If an installation was interrupted, deactivate and activate the plugin again, then clear the cache.

Topdata Enhanced Search SW6 Settings Guide

This guide lists every configuration option of the plugin, grouped by the cards of the plugin settings (Topdata Enhanced Search > Settings). The raw configuration key is shown in the first column, so you can also set it in your config.php if you prefer.

Topdata

The first card only shows the Topdata banner with a link to this manual. It has no settings of its own.

Layout

Controls how many entries each overlay section shows and how the sections are arranged.

SettingDefaultDescription
searchLayoutvertical-accordionSearch layout
maxProducts5Max. products
maxCategories5Max. categories
maxManufacturers3Max. manufacturers
emptyBrandHandlingshow_allBrands without products — Empty brands (0 active products after category exclusion) in the search overlay’s manufacturer suggestions: hide or grey out.
maxConsumables3Max. consumable devices
maxSuggestions5Max. search suggestions

Visibility

Switches individual overlay sections on or off and configures the product cards.

SettingDefaultDescription
showProductsSectiontrueShow products
skuDisplayModehideSKU display
enableTermHighlightingtrueEnable search term highlighting
showCategoriesSectiontrueShow categories
showManufacturersSectiontrueShow manufacturers
showConsumablesSectiontrueShow consumables
showSearchHistorySectiontrueShow recent searches
showSuggestionsSectiontrueShow search suggestions

Notes

skuDisplayMode — Controls whether and how the product number (SKU) is shown in the search overlay’s product cards. “Extra line” displays the SKU below name/subtitle, “Before/After subtitle” appends it to the existing subtitle line. The color can be themed via the “tdes-product-list__sku” CSS class. enableTermHighlighting — Highlights the entered search term in the search overlay’s results (product names, subtitles, SKUs, suggestion/category/manufacturer names and category breadcrumbs). The color is themeable via the “—tdes-color-highlight-*” CSS custom properties or the “tdes-highlight” class.

Search Exclusion

Keeps products out of the storefront search.

SettingDefaultDescription
excludedCategories—Excluded Categories from Search — Products assigned to these categories will not be found via the storefront search.
excludeOnlyMainCategoryfalseExclude only products whose main category is excluded — When enabled, a product is only hidden from the search if an excluded category is its main category. Products that are merely assigned to an excluded category as a secondary category remain findable.

Search Behavior

Fine-tunes how forgiving the product search is.

SettingDefaultDescription
disableFuzzySearchfalseDisable fuzzy search matching

Notes

disableFuzzySearch — Disables the OpenSearch fuzziness parameter (AUTO:3,8) in product search queries. Prevents near-miss words (e.g. “Toiletten” matching “Tabletten”) but also removes fuzzy typo tolerance. Exact, prefix and edge-ngram matching still apply.

Category Suggest

Configures how matching categories are presented in the overlay.

SettingDefaultDescription
categorySuggestLayoutaboveCategory display layout in search suggest — Choose whether matching categories appear above products or to the left side.
categorySuggestLimit8Maximum number of category suggestions — How many matching categories to show in the search suggest dropdown.
categoryBreadcrumbHideRoottrueHide root category in breadcrumb — Removes the first (root) item from category breadcrumbs in the search overlay, e.g. “Hygiene › Papierhandtücher & Spender” instead of “Focus Shop › Hygiene › Papierhandtücher & Spender”.
categoryBreadcrumbMaxParts3Maximum breadcrumb parts before middle truncation — When a category breadcrumb has more than this many ” › “-separated parts, the search overlay keeps only the first and last part, joined with ” … ”.

Search Analytics

Controls whether search terms are logged and consolidated.

SettingDefaultDescription
enabledtrueEnable search logging
autoConsolidatetrueEnable automatic consolidation via scheduled task — Consolidates raw search log entries into the search statistics table every hour. When disabled, you can still run “topdata:enhanced-search:consolidate-search-logs” manually.

Synonym Suggester

Cost and behaviour of the automatic synonym suggestion strategies.

SettingDefaultDescription
maxSuggestionsPerRun50Max suggestions per run — Safety cap for persisted suggestions per run. Candidate terms that yield no suggestion do not consume a slot.
maxTermsPerRun10Terms per strategy per run (window size)
fuzzyMaxEditsShort2Max Levenshtein edits (short terms <=6 chars)
fuzzyMaxEditsLong3Max Levenshtein edits (long terms >6 chars)
highZeroCountThreshold3High zero-count threshold
enabledStrategiesTITLE_MINED,MPN_PREFIX_FAMILY,LLM,THESAURUS_THEN_LLM_FILTEREnabled suggestion strategies (in execution order)
mpnPrefixFamilyMinMembers2Min. variants forming an MPN prefix family
llmProviderNotice—LLM provider status
llmModelIdentifier—LLM model
llmBatchSize5LLM batch size (terms per call) — How many zero-result terms are sent to the LLM in a single chat request.
llmPoolSize50LLM target pool size — How many successful terms of the same language are offered to the LLM as valid target candidates.

Notes

maxTermsPerRun — Each run processes the union of the N most-searched pending terms contributed by every enabled strategy (overridable per run with —max-terms). This is the main cost knob: a run’s duration is dominated by the most expensive enabled strategy. enabledStrategies — Comma-separated list of strategy keys in EXECUTION ORDER, cheapest first: TITLE_MINED, MPN_PREFIX_FAMILY, HEURISTIC, LLM, THESAURUS_THEN_LLM_FILTER. The order controls which strategy runs first — there is no hidden priority. TITLE_MINED maps zero-result terms onto title-mined catalog phrases and is cheap; run search-suggestion:generate-from-titles first. MPN_PREFIX_FAMILY detects cartridge/toner prefix families in product manufacturer numbers and suggests canonical base synonyms (e.g. “TN 247” -> “TN-247”). The HEURISTIC strategy uses Levenshtein distance which often produces semantically wrong suggestions — disable unless you need high-zero-count term flagging. LLM maps zero-result terms to successful terms; THESAURUS_THEN_LLM_FILTER is the most expensive (LLM-curated thesaurus) strategy and should run last. mpnPrefixFamilyMinMembers — Minimum number of manufacturer part numbers sharing a common prefix before the MPN_PREFIX_FAMILY strategy treats them as a family, e.g. TN-247, TN-247M, TN-247BK = 3. Families turn formatting-variant zero-result searches (“TN 247”) into synonym suggestions for the canonical base (“TN-247”). llmModelIdentifier — Chat model used by the “LLM” and external-API strategies. Only chat models are selectable. Leave empty to resolve through the LLM Router purpose chain. Stores a reference to the LLM Connect model, so the provider is derived from the entry and cannot be mismatched.

Search Suggestions from Titles

Rules for mining recurring phrases out of your product titles.

SettingDefaultDescription
suggestionMiningMinProducts3Minimum products per phrase — A title phrase becomes a suggestion only when at least this many distinct active products share it. Overridable per run with —min-products.
suggestionMiningMaxWords4Maximum words per phrase — Only title phrases up to this many canonical tokens are mined (dimensions count as one token, e.g. “120x60x60”). Overridable per run with —max-words.
suggestionMiningIncludeMidTitletrueInclude phrases from anywhere in the title
suggestionMiningLimit0Safety cap per language group (0 = no cap) — Optional safety cap, ranked by the number of products sharing the phrase. Leave 0 to let the “Minimum products per phrase” rule decide alone. Overridable per run with —limit (0 = no cap).
suggestionMiningLanguage—Language filter (empty = all) — Restrict generation to one storefront language group. de and gsw are the same group. Overridable per run with —language.
suggestionMiningTargetQueryorder=topsellerQuery string appended to generated search URLs — Appended to /search?search= when a generated suggestion is clicked, e.g. order=topseller. Leave empty for no suffix.

Notes

suggestionMiningIncludeMidTitle — Also mine multi-word phrases wherever they appear in a product title, e.g. “WC-Papier” from “HAKLE WC-Papier …”. Single words are only mined at the start of a title. Turn off to restore prefix-only mining. Overridable per run with —prefix-only.

Synonym Suggestion Banding (Jev)

Optional AI pre-classification of pending synonym suggestions. Requires topdata/llm-connect-sw6.

SettingDefaultDescription
bandingModeoffBanding mode
bandingModelIdentifier—Jev model
bandingBatchSize20Suggestions per Jev request — How many suggestions are packed into one decisions request (one state array, one noul + score question pair per suggestion).
bandingAutoNoulMin0.9Auto-approve: min. noul probability
bandingAutoScoreMin2.6Auto-approve: min. relevance score — The relevance score is a 0-3 scale (irrelevant / weak / good / exact). 2.6 additionally accepts strong morphological variants (e.g. singular/plural) and regional variants — lower it further only if you accept those as synonyms.
bandingDiscardNoulMax0.2Discard: max. noul probability
bandingDiscardScoreMax1.5Discard: max. relevance score
bandingMinProducts1Min. products for auto-approve — When the target is a title-mined phrase with a known cached product count, auto-approve requires at least this many products; a known count of 0 always discards. Targets without a known count are judged by Jev alone.

Notes

bandingMode — off: no-op. shadow: Jev scores every pending suggestion and persists the AI verdict (AI_APPROVED / AI_UNCERTAIN / AI_DISCARDED) for calibration without acting. active: additionally auto-approves AI_APPROVED verdicts into tdes_synonym and discards AI_DISCARDED ones. shadow is a one-time calibration mode: band a limited sample, review the verdicts in the admin, tune the thresholds, then re-run with —reband and switch to active. Requires topdata/llm-connect-sw6 with the Jev client and an OpenRouter API key stored under the “jev” provider. Run topdata:enhanced-search:synonym-suggestions:band after generation. bandingModelIdentifier — Decision model used to band synonym suggestions. Only decision models (as advertised by the provider catalogue) are selectable. Stores a reference to the LLM Connect model, so the provider is derived from the entry and cannot be mismatched.

Debug

Diagnostic output for troubleshooting.

SettingDefaultDescription
showSearchDurationfalseShow search duration (ms)

Support

For additional support, please contact our technical support team or visit our support portal.

Topdata Enhanced Search SW6 Usage Guide

What the Customer Sees

As soon as a customer types in the storefront search field, the search overlay opens and groups the matches into sections. Which sections appear and how many entries each contains is controlled in the plugin settings (see Settings Guide).

SectionContent
Search suggestionsCurated phrases from your catalogue with a product count, e.g. WC-Papier (12 Artikel)
ProductsMatching products with name, subtitle and — if enabled — the SKU
CategoriesMatching categories, either above the products or next to them
ManufacturersBrands, each with the number of active products it offers
Consumable devicesDevices that the matching consumables belong to
Recent searchesWhat this customer searched for before

The search term is highlighted in every name, subtitle, SKU and breadcrumb. The colours are CSS custom properties, so a theme can restyle the overlay from its own base.scss:

.tdes-overlay {
    --tdes-color-accent: #e96354;
    --tdes-color-highlight-bg: #f2d0c8;
}

The “show all” link on a suggestion opens the suggestion results page (/suggestion-search?search=<term>) with all matching suggestions, each with its target URL and its product count.

Maintaining Search Quality

The plugin collects what your customers search for and turns it into suggestions and synonyms. The workflow has four steps and is meant to run on a schedule.

Step 1 — Let the analytics collect data

Nothing to do: while enabled (Search Analytics) is on, every storefront search is logged per language. A scheduled task consolidates the raw log into statistics every hour. If you switched autoConsolidate off, run the consolidation yourself:

bin/console topdata:enhanced-search:consolidate-search-logs

Review the collected data in the administration under Topdata Enhanced Search > Search Statistics. The Search Log page shows the raw entries. Terms that can never produce a useful synonym — pure numbers such as SKUs or EANs, whole brand names, filler words, very short terms — are flagged as noise and never enter the suggestion workflow.

Step 2 — Mine search suggestions from your product titles

Recurring phrases in your product titles become suggestions:

bin/console topdata:enhanced-search:search-suggestion:generate-from-titles

Useful options:

OptionEffect
--languageRestrict the run to one storefront language (de and gsw are the same group)
--min-productsOverride how many products must share a phrase
--max-wordsOverride the maximum phrase length
--limitCap the number of suggestions per language group (0 = no cap)
--prefix-onlyMine title prefixes only (overrides suggestionMiningIncludeMidTitle)
--skip-countsDo not refresh the cached product counts

Phrases that are shared by fewer products than suggestionMiningMinProducts are ignored. A phrase whose product count is known to be 0 is skipped. Run this before the synonym generation in Step 3 — the title-mined pool is one of its input sources.

Manage the resulting suggestions under Topdata Enhanced Search > Search Suggestions.

Step 3 — Generate synonym suggestions

Terms that returned no results are the interesting ones. The plugin maps them onto terms that did return results:

bin/console topdata:enhanced-search:synonym-suggestion:generate

The strategies run in the order configured in enabledStrategies, cheapest first:

StrategyWhat it does
TITLE_MINEDMaps a zero-result term onto a phrase mined from your product titles
MPN_PREFIX_FAMILYDetects cartridge/toner families that share a manufacturer-number prefix and suggests the canonical base (TN 247 → TN-247)
HEURISTICLevenshtein matching; cheap, but often semantically wrong — enable only if you want to flag high-zero-count terms
LLMAsks a language model to map zero-result terms onto successful ones
THESAURUS_THEN_LLM_FILTERThesaurus candidates narrowed down by an LLM to the product-relevant ones; the most expensive, run last

Options: --strategy (run a single strategy), --language, --max-terms (window size), --limit (cap on stored suggestions), --reset-processed (re-examine terms already processed), --debug, --allow-disabled-strategy.

maxTermsPerRun and maxSuggestionsPerRun are the main cost knobs: a run’s duration is dominated by the most expensive enabled strategy. Each run reports how many terms it marked as processed, so a later run skips them instead of paying for them twice.

The proposals wait for your approval in the administration under Topdata Enhanced Search > Synonym Suggestions. Approving a row writes the synonym; it becomes searchable after bin/console es:index.

Step 4 — Optional: let AI pre-classify the proposals

With topdata/llm-connect-sw6 in place you can have the Jev decision model score every pending suggestion before you look at it. Start in calibration mode:

  1. Set bandingMode to shadow.

  2. Run the banding:

    bin/console topdata:enhanced-search:synonym-suggestions:band --limit 50

    The run ends with three tables — approved / discarded / undecided — each row with its noul probability, relevance score, product count and a note. In shadow mode the headings read “Would be …”: the verdicts are stored but nothing is written to the synonyms.

  3. Adjust bandingAutoScoreMin / bandingAutoNoulMin (and the discard thresholds) to match what you consider a good synonym. The report tells you how many rows a lower score threshold would approve.

  4. When the calibration looks right, re-run with --reband — this re-evaluates everything the AI decided and returns the uncertain rows to your queue — then switch bandingMode to active.

In active mode, AI_APPROVED rows are written to the synonyms automatically and AI_DISCARDED rows are closed. Two hard rules always win: a target with a known product count of 0 is discarded, and a target below bandingMinProducts can never be approved. Any error in the AI call fails open — the rows simply stay pending. Options: --dry-run, --limit, --language, --type, --reband.

Keep in mind that the relevance score is a judgement, not a measurement: re-banding the same row can move its score slightly, so judge a threshold from a full run rather than one row.

Everyday Synonym Work

Under Topdata Enhanced Search > Synonyms you manage the active synonym rules. Each rule has a search term, one or more mapped terms, a scope (all languages or a single one) and a boost level (NONE, LOW, MEDIUM, HIGH) that promotes the mapped terms in the result scoring.

  • Editing or adding a rule requires bin/console es:index afterwards.
  • Changing only a boost level takes effect immediately, without a reindex.
  • Exports and imports are asymmetric and source-preserving (term => term, targets), so a product that literally matches the source term keeps its normal matches:
# back up the current rules
bin/console topdata:enhanced-search:synonym:export --output synonyms-backup.txt

# check a file's syntax before importing it
bin/console topdata:enhanced-search:synonym:import synonyms.txt --dry-run

# import rules from a text file, then reindex
bin/console topdata:enhanced-search:synonym:import synonyms.txt
bin/console es:index

Related pages: Synonym Sources (configured CSV imports), Synonym APIs (external sources), Filter Map (hide specific products from the results of a mapped search term) and Search stopwords (words the title mining must never end a suggestion on).

Useful Commands

# synonyms
bin/console topdata:enhanced-search:synonym:list
bin/console topdata:enhanced-search:synonym:validate synonyms.txt
bin/console topdata:enhanced-search:synonym:delete "papier"
bin/console topdata:enhanced-search:synonym:clear

# suggestions
bin/console topdata:enhanced-search:synonym-suggestion:list
bin/console topdata:enhanced-search:search-suggestion:clear
bin/console topdata:enhanced-search:synonym-suggestion:clear

# diagnostics: shows how the products for a term are scored
bin/console topdata:enhanced-search:debug-search "papier"

Support

For additional support, please contact our technical support team or visit our support portal.

Topdata Enhanced Search SW6 FAQ & Troubleshooting

Common Issues

SymptomLikely CauseSolution
The search overlay does not openThe plugin is not active, or the search index was never rebuiltbin/console plugin:list, then bin/console es:index
A newly added synonym has no effectThe index still holds the old synonym setbin/console es:index
A synonym works but a product matching the term disappeared from the resultsThe rule redirects the term; exports/imports are source-preserving (term => term, targets), so add the term itself to the target listEdit the rule so the source term is included, then reindex
Search results contain obviously wrong products (e.g. “Toiletten” finds “Tabletten”)Fuzzy matching is activeEnable disableFuzzySearch, then reindex — or use the Filter Map to exclude the product from that term
Correct products are missing from the resultsThey are assigned to an excluded categoryReview excludedCategories; if the products are only assigned to it as a secondary category, enable excludeOnlyMainCategory
Brands with no products clutter the manufacturer listEmpty brands are shown by defaultSet emptyBrandHandling to hide_empty or grey_empty
Category names in the overlay are too longLong breadcrumbsIncrease categoryBreadcrumbMaxParts or disable categoryBreadcrumbHideRoot
The synonym generation finds nothingNo terms with zero results have been collected yet, or all of them were marked as processedLet the analytics run for a while, check Search Statistics, and use --reset-processed
A generation run is very slowAn expensive strategy is enabledRemove THESAURUS_THEN_LLM_FILTER from enabledStrategies or lower maxTermsPerRun
No synonym suggestions are generated although the LLM is configuredThe LLM strategy was removed because topdata/llm-connect-sw6 is missingInstall the plugin and store a credential under Topdata Llm Connect > AI Credentials
AI banding does nothingbandingMode is still off, or the Jev provider has no API keySet bandingMode to shadow for calibration; verify the credential for the provider jev
Product counts next to suggestions are staleThe catalogue changed after the last mining runRe-run topdata:enhanced-search:search-suggestion:generate-from-titles without --skip-counts; counts older than the active index are recomputed automatically
The overlay colours do not match the themeThe theme does not override the CSS custom propertiesSet the --tdes-color-* variables on .tdes-overlay in the theme’s base.scss

Troubleshooting Guide

1. The search returns nothing after an update

Shopware 6.7 uses a real edge-ngram tokenizer for the plugin’s index field. After an update the index must be rebuilt, otherwise the new matching rules are not in place:

bin/console cache:clear
bin/console es:index

2. Checking how a term is scored

Use the debug command to see which products a term matches and how they are scored:

bin/console topdata:enhanced-search:debug-search "papier"

With --sales-channel-id and --language-id you can inspect a specific sales channel and language, --limit shortens the output.

3. A synonym file does not import

Validate the file first — it reports the offending line instead of failing halfway through:

bin/console topdata:enhanced-search:synonym:validate synonyms.txt
bin/console topdata:enhanced-search:synonym:import synonyms.txt --dry-run

A rule has the form [language,product,boost=LEVEL] term => syn1, syn2. Only chat models can be selected for the LLM strategies and only decision models for the Jev banding.

4. Reverting an AI decision that was wrong

Run the banding again with --reband: it re-evaluates every row the AI decided, including the ones it discarded, and returns rows that come back undecided to the human queue. Rows a person has decided are never touched. After new synonyms were written, rebuild the index.

5. Temporarily disabling the AI parts

Set bandingMode to off and remove LLM and THESAURUS_THEN_LLM_FILTER from enabledStrategies. Everything else — analytics, title mining, MPN_PREFIX_FAMILY, the existing synonyms — keeps working without any AI credential.

Support

For additional support, please contact our technical support team or visit our support portal.