Skip to content

Commit 1e2983a

Browse files
vienthuongIsengo1989
vienthuong
and
Isengo1989
authored
docs(elasticsearch): document search relevance configuration options (#2342)
* docs(elasticsearch): document search relevance configuration options - Add the SHOPWARE_ES_DIMENSION_NORMALIZE environment variable (dimensional notation normalization, disabled by default, reindex required). - Add a "Configuring search relevance" section to the Elasticsearch guide covering core.search.minScore, elasticsearch.search.dismax_tie_breaker, the other elasticsearch.search settings (timeout, term_max_length, search_type, precision_threshold), the analyzer environment variables, and the storefront redirect_on_single_hit_fields parameter. - Document Advanced Search strictness-based matching as a decimal (0.0-1.0), including the ceil(terms x strictness) rule, how to set it, and that the enableAdvancedSearchStrictnessPresets flag only affects the admin UI. - Document Advanced Search German compound-word decomposition. Version notes: platform 6.7.12.0 for core features; Commercial 7.11.0 for strictness and 7.12.0 for compound-word decomposition. * fix/grammar-and-wording-tables --------- Co-authored-by: Micha <m.hobert@shopware.com>
1 parent 23aef34 commit 1e2983a

4 files changed

Lines changed: 80 additions & 2 deletions

File tree

‎guides/hosting/configurations/shopware/environment-variables.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,13 +41,14 @@ This page lists all environment variables that can be used to configure Shopware
4141
| `REDIS_URL` | (empty) | Redis connection URL for caching and sessions (example: `redis://host:port`) |
4242
| `SHOPWARE_ADMIN_ES_ENABLED` | (empty) | Enable Elasticsearch for administration |
4343
| `SHOPWARE_ADMIN_ES_INDEX_PREFIX` | `sw-admin` | Index prefix for administration Elasticsearch |
44-
| `SHOPWARE_ADMIN_ES_INDEXING_BATCH_SIZE` | `1000` | Batch size for administration Elasticsearch indexing (since 6.7.9.0) |
44+
| `SHOPWARE_ADMIN_ES_INDEXING_BATCH_SIZE` | `1000` | Batch size for administration Elasticsearch indexing (since 6.7.9.0) |
4545
| `SHOPWARE_ADMIN_ES_REFRESH_INDICES` | (empty) | Refresh administration indices |
46-
| `SHOPWARE_ADMIN_ES_THROW_EXCEPTION` | `1` | Whether to throw exceptions on administration Elasticsearch errors (`1` to enable, `0` to disable). Mainly useful in local development for debugging (since 6.7.9.0) |
46+
| `SHOPWARE_ADMIN_ES_THROW_EXCEPTION` | `1` | Whether to throw exceptions on administration Elasticsearch errors (`1` to enable, `0` to disable). Mainly useful in local development for debugging (since 6.7.9.0) |
4747
| `SHOPWARE_ADMINISTRATION_PATH_NAME` | `admin` | Custom path name for administration interface |
4848
| `SHOPWARE_DBAL_TIMEZONE_SUPPORT_ENABLED` | `0` | Enable timezone support in DBAL |
4949
| `SHOPWARE_DBAL_TOKEN_MINIMUM_LENGTH` | `3` | Minimum token length for DBAL (@deprecated v6.8.0) |
5050
| `SHOPWARE_DISABLE_UPDATE_CHECK` | (empty) | Disable automatic update checks |
51+
| `SHOPWARE_ES_DIMENSION_NORMALIZE` | `0` | Normalizes dimensional notation in the technical-term analyzer chains so that spaced and joined forms match (for example `5 x 70` → `5x70`). Disabled by default; enabling it requires a full reindex via `bin/console es:index` (since 6.7.12.0). |
5152
| `SHOPWARE_ES_ENABLED` | `0` | Open Search Support Enabled? |
5253
| `SHOPWARE_ES_EXCLUDE_SOURCE` | `0` | Exclude source from Elasticsearch |
5354
| `SHOPWARE_ES_INDEX_PREFIX` | (empty) | Open Search Index Prefix |

‎guides/plugins/plugins/integrations/elasticsearch/index.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,48 @@ nav:
88
# Elasticsearch
99

1010
By extending fields of an entity to the Elasticsearch engine, you expand the search capabilities of Shopware, allowing users to search based on additional attributes or metadata. This enhances the overall search experience and enables more targeted and precise search results for customers.
11+
12+
## Configuring search relevance
13+
14+
Several aspects of the product search relevance can be configured without custom code.
15+
16+
### Minimum score
17+
18+
`core.search.minScore` (since 6.7.12.0) is a system configuration value (per sales channel, default `0.0`). When greater than `0.0`, product-search hits scoring below the threshold are dropped, which trims the long tail of weak matches. Leave it at `0.0` to disable the cutoff.
19+
20+
There is no universally correct value — the effective score range depends on field weights, analyzer configuration, and catalog size — so start low and increase it gradually while watching how noisy queries behave. Set it through the Administration, the Admin API, or the console:
21+
22+
```bash
23+
bin/console system:config:set core.search.minScore 5.0
24+
```
25+
26+
### Multi-field tie-breaker
27+
28+
When a query matches a product in more than one field, the per-field scores are combined with a `dis_max` query. The `tie_breaker` (since 6.7.12.0, default `0.2`, range `0.0`–`1.0`) controls how much the non-best field matches contribute to the final score. Override it in `config/packages/elasticsearch.yaml`:
29+
30+
```yaml
31+
elasticsearch:
32+
search:
33+
dismax_tie_breaker: 0.3
34+
```
35+
36+
### Other search settings
37+
38+
The `elasticsearch.search` section holds further settings you can override in `config/packages/elasticsearch.yaml`:
39+
40+
```yaml
41+
elasticsearch:
42+
search:
43+
timeout: 5s # request timeout per search
44+
term_max_length: 300 # search terms longer than this are truncated
45+
search_type: query_then_fetch # OpenSearch search type
46+
# precision_threshold: 40000 # cardinality accuracy for grouped product counts (higher = more memory)
47+
```
48+
49+
### Analyzer settings
50+
51+
Analyzer behavior is controlled through environment variables, including `SHOPWARE_ES_DIMENSION_NORMALIZE`, `SHOPWARE_ES_NGRAM_MIN_GRAM` / `SHOPWARE_ES_NGRAM_MAX_GRAM`, and `SHOPWARE_ES_USE_LANGUAGE_ANALYZER` — see [Environment Variables](../../../../hosting/configurations/shopware/environment-variables.md). Changing any analyzer setting requires a full reindex with `bin/console es:index`.
52+
53+
### Direct redirect for exact code matches
54+
55+
The storefront search redirects straight to the product page when a search returns a single product whose `productNumber`, `ean`, or `manufacturerNumber` exactly matches the query. This applies regardless of the search backend (Elasticsearch or the database). The fields that trigger the redirect are controlled by the `shopware.storefront.redirect_on_single_hit_fields` parameter (default `['productNumber', 'ean', 'manufacturerNumber']`) — override it to restrict the behavior, or set it to an empty list to disable the redirect. The `ean` and `manufacturerNumber` fields were added to the default since 6.7.12.0.

‎products/extensions/advanced-search/How-to-add-modify-language-analyzers-stopwords-stemmer.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,16 @@ advanced_search:
3434
language_analyzer_mapping:
3535
custom_iso: sw_your_custom_language_analyzer
3636
```
37+
38+
## Compound-word decomposition
39+
40+
German catalogs often contain closed compound nouns (for example `Lederjacke` or `Akkubohrer`). Without decomposition, a search for `Jacke` does not match a product named `Lederjacke`.
41+
42+
Since Commercial 7.12.0, Advanced Search ships a `dictionary_decompounder` filter that splits compound words into their parts at index time, using an editable, per-language dictionary. A curated German root-word dictionary is seeded by default. Decomposition is applied at index time only, on the technical-term index analyzer (`sw_<iso>_technical_term_index_analyzer`); the search query itself is never expanded into its parts.
43+
44+
The dictionaries are stored as entities and can be managed through the Admin API:
45+
46+
* `advanced_search_compound_dictionary` — the `wordList` of root words used to split compounds.
47+
* `advanced_search_stopword_dictionary` — custom `stopwords`, which are stripped at both index and search time.
48+
49+
After editing a dictionary, run `bin/console es:index` so the updated analyzer configuration is applied to the index.

‎products/extensions/advanced-search/How-to-modify-search-logic.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,3 +72,22 @@ class SearchLogicDecorator extends AbstractSearchLogic
7272
}
7373
}
7474
```
75+
76+
## Strictness-based matching
77+
78+
Besides the binary `AND` / `OR` operators, the search behavior can be configured with a strictness value (since Commercial 7.11.0) — a decimal between `0.0` and `1.0` that defines the share of the search terms a product must match. It is stored per sales channel in the `strictness` field of the `advanced_search_config` entity (default `1.0`); the legacy `and_logic` flag is deprecated in its favor.
79+
80+
* `0.0` — at least one term must match (equivalent to `OR`).
81+
* `1.0` — all terms must match (equivalent to `AND`).
82+
* A value in between requires `ceil(numberOfTerms × strictness)` terms to match. For example, the query `blue running shoes` (3 terms) with `0.5` requires `ceil(3 × 0.5) = 2` of the terms to match.
83+
84+
The `strictness` field drives the search behavior on its own — no feature flag is required for it to take effect.
85+
86+
To edit it as presets in the Administration (the **Search behavior** section), enable the `SwagCommercial.config.enableAdvancedSearchStrictnessPresets` system configuration. The UI then offers the presets `0`, `0.33`, `0.5`, `0.66`, and `1`; otherwise it shows the legacy `AND` / `OR` toggle (which maps to `1.0` / `0.0`). Regardless of that flag, you can set any decimal between `0.0` and `1.0` directly through the Admin API:
87+
88+
```bash
89+
PATCH /api/advanced-search-config/{id}
90+
{
91+
"strictness": 0.5
92+
}
93+
```

0 commit comments

Comments
 (0)