Table of contents :

Minimum Should Match for Smarter Queries

100-days-of-elasticsearch-woocommerce-030

Table of contents :

WooCommerce product search often combines several optional clauses: product title, SKU, categories, attributes, brands, and synonyms. A broad bool query can return products that match only one weak clause, producing results that are technically relevant but not useful to shoppers. Elasticsearch’s minimum_should_match parameter lets you require a sensible number of those optional clauses to match.

How minimum_should_match works

Use minimum_should_match inside a bool query with a should array. The value determines how many should clauses must match before a document can be returned.

{ "query": { "bool": { "should": [ { "match": { "name": { "query": "red running shoes", "boost": 4 } } }, { "match": { "short_description": "red running shoes" } }, { "term": { "categories.slug": "running-shoes" } }, { "term": { "attributes.color.keyword": "red" } } ], "minimum_should_match": 2 } } }

In this example, a product must match at least two of the four optional clauses. A product matching the title and category is eligible, while a product matching only a loosely related description is excluded.

Choosing the right expression

  • Integer: 2 requires exactly two matching clauses.
  • Positive percentage: 75% requires 75% of the clauses to match.
  • Negative percentage: -25% allows up to 25% of the clauses to be missing.
  • Combination: 2<-25% 9<-3 can require two matches for smaller clause sets, allow 25% missing for medium sets, and allow only three missing clauses for larger sets.
  • Zero: 0 makes every should clause optional, so the clauses influence scoring but do not determine eligibility.

Percentages are rounded down when Elasticsearch calculates the required count. For example, 75% of five clauses evaluates to three required matches, while -25% permits one missing clause and therefore requires four matches. Test expressions with the actual number of clauses generated by your integration.

Default behavior can be surprising

The default minimum depends on the surrounding Boolean query. If a bool query contains only should clauses, Elasticsearch normally requires at least one to match. If the same query also contains a must or filter clause, the should clauses are optional by default and primarily affect relevance scoring.

{ "query": { "bool": { "filter": [ { "term": { "stock_status": "instock" } } ], "should": [ { "match": { "name": "waterproof jacket" } }, { "match": { "description": "waterproof jacket" } } ] } } }

Here, the stock filter is mandatory, but neither text clause is required unless a minimum_should_match value is set. For a WooCommerce search endpoint, explicitly setting the value makes the behavior stable when filters, visibility rules, price ranges, or vendor constraints are added later.

Using it with analyzed product text

For a multi-field product search, use a multi_match query when the same user input should be searched across several fields. The minimum_should_match setting inside multi_match applies to the analyzed query terms, not to separate field clauses.

{ "query": { "bool": { "filter": [ { "term": { "post_type": "product" } }, { "term": { "catalog_visibility": "visible" } } ], "must": [ { "multi_match": { "query": "black leather travel bag", "fields": [ "name^5", "sku^3", "short_description", "description" ], "type": "best_fields", "operator": "or", "minimum_should_match": "2<-25%" } } ] } } }

This requires all terms for short queries of up to two terms, while allowing a percentage of terms to be absent for longer queries. The exact behavior should match the search experience you want: strict matching improves precision, while a lower threshold preserves recall for incomplete product names and spelling variations.

Combining independent relevance signals

When each signal represents a separate product attribute, put the clauses in a top-level should array and set the threshold there. This is useful when an agency needs title, SKU, taxonomy, and attribute matches to contribute independently.

{ "query": { "bool": { "must": [ { "match": { "name": "coffee grinder" } } ], "should": [ { "term": { "brand.keyword": "acme" } }, { "term": { "attributes.burr_type.keyword": "conical" } }, { "term": { "categories.slug": "coffee-grinders" } } ], "minimum_should_match": 1 } } }

The mandatory name match identifies the product family, and at least one additional signal must match. Use boosts to rank stronger matches rather than lowering the threshold until unrelated products appear.

WooCommerce implementation practices

  1. Build clauses deliberately. Do not count empty SKU, brand, or attribute clauses. A dynamic query builder should add a clause only when the corresponding indexed value exists.
  2. Separate eligibility from ranking. Put stock, product type, visibility, language, and tenant restrictions in filter. Use should and minimum matching for relevance signals.
  3. Keep exact matching fields keyword-based. Use term queries for normalized SKU, slug, brand, and attribute values. Use match or multi_match for analyzed names and descriptions.
  4. Measure zero-result rates. A threshold that works for a small catalog may be too strict after importing products with sparse attributes or translated content.
  5. Test generated queries. Log the final Elasticsearch request for representative searches, including one-word searches, long queries, SKUs, synonyms, and searches with active filters.

Practical tuning strategy

Start with a low explicit threshold, such as 1 for independent fields or 2<-25% for analyzed terms. Compare precision, click-through rate, add-to-cart rate, and zero-result rate against the current search. If irrelevant products dominate, increase the threshold or strengthen field boosts. If valid products disappear, reduce the threshold, improve analyzers and synonyms, or avoid requiring sparse metadata fields.

For agencies maintaining several WooCommerce stores, keep the threshold configurable per index or storefront. Product catalogs differ in field completeness, language, and attribute conventions, so one fixed value should not be treated as a universal default.

Trending posts
You might also like