Phrase matching is useful when WooCommerce shoppers enter a sequence of words that should remain together, such as stainless steel bottle, wireless gaming mouse, or men's running shoes. Unlike a broad full-text query, a phrase query checks both the presence and the order of the terms. This can make product search results more predictable without requiring an exact match of the entire product title.
Why phrase matching matters in WooCommerce
WooCommerce catalogs often contain overlapping terms. A search for wireless gaming mouse should usually prioritize products containing that sequence over products that mention wireless, gaming, and mouse in unrelated parts of the description.
A regular match query analyzes the input and generally matches the terms independently. A match_phrase query adds a positional requirement: the analyzed terms must occur in the same order and within the allowed distance from one another.
Basic Elasticsearch phrase query
{
"query": {
"match_phrase": {
"post_title": {
"query": "wireless gaming mouse"
}
}
}
}For a WooCommerce index, post_title might contain the product name, while additional fields could store the SKU, short description, long description, category names, and attributes. The field name must match the mapping used by the agency’s indexing process.
Combining phrase matching with broader search
Phrase matching is often too restrictive as the only query. A shopper may enter a phrase that differs slightly from the wording in the catalog, or the product title may contain an additional word between the important terms. A bool query can give phrase matches more relevance while retaining a broader fallback.
{
"query": {
"bool": {
"should": [
{
"match_phrase": {
"post_title": {
"query": "wireless gaming mouse",
"boost": 5
}
}
},
{
"multi_match": {
"query": "wireless gaming mouse",
"fields": [
"post_title^4",
"sku^3",
"short_description",
"description",
"attributes"
],
"operator": "and"
}
}
],
"minimum_should_match": 1
}
}
}Here, an exact phrase in the product title receives a stronger score, but products containing all analyzed terms across the configured fields can still be returned. The boost should be tested against real WooCommerce search logs rather than selected arbitrarily.
Allowing small gaps with slop
Real catalog text may include modifiers between the shopper’s terms. For example, a title such as wireless ergonomic gaming mouse does not contain the exact phrase wireless gaming mouse, but it may still be highly relevant. The slop parameter allows a limited positional distance.
{
"query": {
"match_phrase": {
"post_title": {
"query": "wireless gaming mouse",
"slop": 1,
"boost": 4
}
}
}
}A low slop value is usually safer for product search. Increasing it too far weakens the phrase signal and can make unrelated text appear relevant. Slop is also affected by token positions, so stop-word handling, synonyms, and analyzer configuration should be tested with the actual field mapping.
Phrase matching across multiple WooCommerce fields
multi_match with type set to phrase applies phrase matching to several fields.
{
"query": {
"multi_match": {
"query": "stainless steel bottle",
"type": "phrase",
"fields": [
"post_title^5",
"short_description^2",
"description",
"attributes"
],
"slop": 0
}
}
}Use field boosts to reflect WooCommerce search intent. Product titles and structured attributes normally deserve more weight than long descriptions. If the fields use different analyzers, verify that the phrase query behaves consistently across them.
Phrase prefix for incomplete searches
match_phrase expects all analyzed terms to be present. For search-as-you-type interfaces, match_phrase_prefix allows the final term to be treated as a prefix.
{
"query": {
"match_phrase_prefix": {
"post_title": {
"query": "wireless gam"
}
}
}
}This can match titles beginning with a phrase such as wireless gaming. Phrase-prefix queries may expand the final term into many indexed terms, so apply sensible limits and test latency on large catalogs. For high-volume autocomplete, Elasticsearch completion fields or dedicated search-as-you-type mappings may be more appropriate.
Handling phrase queries in a WooCommerce search request
An application layer can add phrase clauses only when the query contains multiple meaningful terms. A simplified PHP example for an Elasticsearch request body might look like this:
$searchTerm = trim($request->get_param('s'));
$body = [
'query' => [
'bool' => [
'should' => [
[
'match_phrase' => [
'post_title' => [
'query' => $searchTerm,
'boost' => 5,
],
],
],
[
'multi_match' => [
'query' => $searchTerm,
'fields' => [
'post_title^4',
'sku^3',
'short_description',
'description',
],
],
],
],
'minimum_should_match' => 1,
],
],
];In production, validate the search term, enforce request timeouts, and keep pagination limits under control. Phrase matching should be added to the Elasticsearch query before result IDs are converted into WooCommerce product responses. If the integration uses the WordPress REST API or a custom WP_Query bridge, keep the Elasticsearch relevance logic separate from post-hydration and access-control checks.
Analyzers, synonyms, and field mappings
Phrase behavior depends on analysis. Lowercasing normally allows Wireless Gaming Mouse to match the same indexed terms as the lowercase query. Stemming can change terms, while stop-word filters can remove tokens and alter their positions. Synonym rules require particular care because equivalent terms may expand into multiple tokens or token graphs.
For product names, many teams use a dedicated text field for analyzed search and a keyword subfield for exact filtering and aggregations:
{
"mappings": {
"properties": {
"post_title": {
"type": "text",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
}
}
}
}Do not use the keyword subfield for normal phrase matching. It treats the complete product title as one token and is intended for exact-value operations, sorting, and aggregations.
Testing relevance and performance
Create a test set from real WooCommerce searches and record the products that should rank highest for each query. Include singular and plural terms, punctuation, stop words, SKU searches, attribute phrases, and titles with inserted modifiers. Compare a broad query with the phrase-boosted version using the same catalog snapshot.
- Use the Elasticsearch
_analyzeAPI to inspect the tokens produced by the configured analyzer. - Use the
_explainAPI for individual products when a phrase result receives an unexpected score. - Measure query latency with realistic catalog size, shard count, filters, and pagination.
- Check searches containing very common terms, which can produce large candidate sets.
- Monitor zero-result rates so an overly strict phrase clause does not hide otherwise relevant products.
A practical WooCommerce strategy is to use phrase matching as a high-value relevance signal, combine it with field-aware full-text matching, and reserve strict phrase-only behavior for workflows where the entered wording must be preserved.