Should You Use Match or Term for WooCommerce?

Choosing between match and term queries affects whether WooCommerce product search behaves like a customer-facing search experience or an exact filtering system. The right choice depends on how the field is mapped and whether the input should be analyzed.

The practical difference

A match query is designed for analyzed text. Elasticsearch processes the search input with the field’s analyzer, usually converting it into one or more searchable terms. This makes it suitable for product names, descriptions, and other fields where customers may enter natural language.

A term query searches for an exact indexed term. Elasticsearch does not analyze the value supplied to a term query. It is therefore appropriate for exact identifiers and filters, such as product IDs, SKUs, stock flags, brand codes, or taxonomy IDs mapped as keywords.

Use match for customer-facing product text

Consider a product name field mapped as text. A customer searching for waterproof hiking boots generally expects products whose names contain those words, regardless of capitalization and depending on the analyzer, tokenization and language processing.

{"query":{"match":{"name":{"query":"waterproof hiking boots"}}}}

The analyzer may tokenize the input into separate terms. The resulting behavior is controlled by options such as operator, minimum_should_match, fuzziness, and the field’s mapping. For a stricter all-words requirement, an agency might use:

{"query":{"match":{"name":{"query":"waterproof hiking boots","operator":"and"}}}}

Use match_phrase when word order and adjacency matter. This can be useful when a product title contains a known phrase, although it is usually too restrictive as the only query in a general WooCommerce search.

{"query":{"match_phrase":{"name":"waterproof hiking boots"}}}

Use term for exact WooCommerce filters

A term query is a good fit for fields mapped as keyword. For example, a product index might store a WooCommerce SKU in a field named sku and an indexed stock state in stock_status.

{"query":{"bool":{"filter":[{"term":{"sku":"WB-100-BLK"}},{"term":{"stock_status":"instock"}}]}}}

Putting exact constraints in the filter clause communicates intent and avoids relevance scoring. It can also improve efficiency because filter results may be eligible for Elasticsearch caching and do not contribute to the document score.

Other common term-based filters include a numeric or keyword product category ID, a brand slug, a visibility value, a language code, or a boolean-like field represented consistently as a keyword. Confirm the actual mapping and indexed value before choosing the query.

The keyword subfield is often the answer

WooCommerce search indexes commonly map a product field with both analyzed and exact representations:

{"name":{"type":"text","fields":{"keyword":{"type":"keyword"}}}}

With this mapping, use match against name for relevance-based search and term against name.keyword for exact matching or aggregations.

{"query":{"bool":{"must":[{"match":{"name":"trail jacket"}}],"filter":[{"term":{"name.keyword":"Trail Jacket"}}]}}}

Do not assume that every text field has a .keyword subfield. Mappings may be customized, and some WooCommerce integrations use names such as raw, exact, or a dedicated SKU field instead.

Why term can appear to fail

The most frequent implementation mistake is using term against an analyzed text field or supplying the original human-readable value to a normalized keyword field.

For example, if an analyzer converts Red Shoes into the tokens red and shoes, a term query for Red Shoes looks for one exact term containing a space and will not match those tokens. A term query for red might match, but it would not represent an exact product name.

Keyword fields can also use a normalizer that lowercases values. If sku is normalized to lowercase at index time, the query value must be handled consistently, or the integration should use a keyword-aware query builder that applies the same normalization rules.

A typical WooCommerce query combines both

Product search usually needs relevance for text and exact filtering for catalog constraints. A combined query can search names and descriptions while filtering by visibility, stock status, and a selected brand:

{"query":{"bool":{"must":[{"multi_match":{"query":"waterproof hiking boots","fields":["name^3","short_description","description"]}}],"filter":[{"term":{"catalog_visibility":"visible"}},{"term":{"stock_status":"instock"}},{"term":{"brand_slug":"acme"}}]}}}

Here, multi_match is appropriate for analyzed product content, while term filters enforce exact catalog rules. In a production integration, verify whether the connector stores values as strings, numbers, booleans, or arrays, because the query value must match the field mapping.

Decision checklist for agencies

• Use match or multi_match for product names, descriptions, and other analyzed customer search fields.
• Use match_phrase when an exact word sequence is important but the field remains analyzed.
• Use term in filters for exact identifiers, slugs, statuses, flags, and taxonomy values mapped as keywords.
• Use a .keyword or equivalent exact subfield when a field supports both full-text search and exact matching.
• Inspect the index mapping and test representative indexed values with the Elasticsearch Analyze API before debugging query logic.
• Keep exact filters in bool.filter unless the condition is intentionally part of relevance scoring.

The query choice should follow the index mapping, not the WooCommerce field label. A field called “SKU” is normally an exact keyword, while a field called “product name” is normally analyzed text, but custom importers and plugins can map either differently.