Search quality in a WooCommerce store depends on more than matching product titles against a query. Elasticsearch first converts text into searchable terms, and the rules used for that conversion are defined by analyzers. A well-designed analyzer can make searches tolerant of punctuation, capitalization, accents, plurals, and common product terminology without changing the data stored in WooCommerce.
For agencies, analyzers are especially important when implementing product search across multiple stores. A suitable configuration must reflect the catalog’s language, SKU conventions, brand names, attributes, and customer search behavior. It must also be introduced safely because analyzer changes generally require a new index and reindexing.
What an analyzer does
An analyzer is a processing pipeline used for full-text fields. It normally contains three stages:
- Character filters modify the original character stream before tokenization. They can remove HTML or apply mappings.
- A tokenizer splits the character stream into terms, such as words, numbers, or segments separated by punctuation.
- Token filters modify, remove, or add tokens. Examples include lowercasing, stemming, stop-word removal, synonym handling, and edge n-gram generation.
For example, the value Men's Running Shoes - Blue might be converted into terms such as men, running, shoes, and blue. The exact result depends on the character filters, tokenizer, and token filters configured for the field.
Index analyzers and search analyzers
Elasticsearch can use one analyzer when a value is indexed and another when a customer query is processed. The analyzer setting defines the index-time analyzer, while search_analyzer defines the analyzer used for queries.
This separation is useful when indexing requires additional terms but queries should remain conservative. A common example is autocomplete. Product text can be indexed with edge n-grams so that a query for run can match running, while the search analyzer uses ordinary word tokens and does not generate partial query terms.
Using different analyzers is not automatically better. They must produce compatible terms. If index-time analysis creates terms that the search analyzer cannot reasonably reproduce or target, relevance can become difficult to predict. Test both sides with the Analyze API before deploying a configuration.
Built-in analyzers useful for WooCommerce
Standard analyzer
The standard analyzer uses the Unicode Text Segmentation algorithm to split text and applies lowercase filtering. It is a reasonable default for general product names and descriptions when the catalog does not require specialized behavior.
It is not a complete solution for every store. It does not understand that a SKU such as ABC-123-X may be a single business identifier, and it does not provide domain-specific synonym or autocomplete behavior.
Simple analyzer
The simple analyzer splits text at characters that are not letters and lowercases the resulting terms. It can be suitable for basic prose, but it discards numbers, which makes it unsuitable for many product catalogs containing model numbers, sizes, and technical specifications.
Whitespace analyzer
The whitespace analyzer splits only on whitespace. Punctuation remains attached to terms, so ABC-123 and ABC-123, may be treated differently. It is rarely appropriate for customer-facing product search unless the catalog uses carefully controlled values.
Keyword analyzer
The keyword analyzer treats the entire value as one token. It is useful for exact identifiers such as a normalized SKU, an external product ID, or a brand code. It should not normally be used for a product title because a complete title would have to match as one term.
Language analyzers
Language-specific analyzers can provide stemming and stop-word handling for languages such as English, French, German, and Spanish. They can improve recall for natural-language descriptions, but stemming may be undesirable for brand names, model numbers, and carefully controlled attributes. A product title often benefits from a different strategy than a long description.
A practical custom analyzer
A custom analyzer gives an agency control over the processing chain. The following example defines a general-purpose analyzer for English product text and a separate analyzer for autocomplete.
PUT products-v2
{
"settings": {
"analysis": {
"filter": {
"product_edge": {
"type": "edge_ngram",
"min_gram": 2,
"max_gram": 15
},
"english_stop_custom": {
"type": "stop",
"stopwords": "_english_"
}
},
"analyzer": {
"product_text_index": {
"type": "custom",
"tokenizer": "standard",
"filter": [
"lowercase",
"english_stop_custom",
"stemmer"
]
},
"product_text_search": {
"type": "custom",
"tokenizer": "standard",
"filter": [
"lowercase"
]
},
"product_autocomplete_index": {
"type": "custom",
"tokenizer": "standard",
"filter": [
"lowercase",
"product_edge"
]
}
}
}
},
"mappings": {
"properties": {
"name": {
"type": "text",
"analyzer": "product_text_index",
"search_analyzer": "product_text_search",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
},
"autocomplete": {
"type": "text",
"analyzer": "product_autocomplete_index",
"search_analyzer": "product_text_search"
},
"sku": {
"type": "keyword",
"normalizer": "lowercase"
}
}
}
}
The stemmer filter in this abbreviated example uses Elasticsearch's default language setting unless a language is specified. In production, define the language explicitly when the catalog requires predictable behavior. For example, an English stemmer can be configured with "language": "light_english" or another documented English algorithm.
The name field is multi-field data. Its text value supports full-text relevance, while name.keyword supports exact filters, sorting, and aggregations. The SKU remains a keyword because searching and filtering an identifier is usually different from searching natural-language text.
Use the Analyze API before mapping a field
The Analyze API shows the actual tokens produced by an analyzer. This is one of the fastest ways to identify unexpected behavior before importing a large WooCommerce catalog.
POST products-v2/_analyze
{
"analyzer": "product_text_index",
"text": "Men's Running Shoes, Size 10"
}
Inspect the output for terms that matter to customers. Confirm that capitalization is normalized, numbers are retained when required, punctuation behaves as expected, and stemming does not damage important words. Repeat the test with customer-style queries using the search analyzer.
POST products-v2/_analyze
{
"analyzer": "product_text_search",
"text": "running shoe"
}
Agencies should keep representative analysis fixtures in version control. Include product names, SKUs, variation attributes, brand names, accented terms, hyphenated model numbers, and real search queries from WooCommerce analytics.
Handling SKUs, model numbers, and punctuation
SKU search often needs a separate field from title search. A customer may enter ABC123, while the catalog contains ABC-123. A standard tokenizer may not produce the desired relationship. Options include normalizing the source value before indexing, creating a character mapping filter, or indexing additional normalized SKU fields.
One practical approach is to store both the original and normalized values:
skustores the canonical SKU as a keyword for exact matching and display.sku_normalizedstores a lowercase, punctuation-normalized value for lookup.nameand description fields use natural-language analyzers.
Do not apply aggressive punctuation removal to every field. Removing separators may improve SKU recall but can make product names or technical values ambiguous. Keep identifier logic isolated and test it against collisions.
Synonyms and WooCommerce terminology
Synonyms can connect customer language with catalog language. Examples include sneakers and trainers, or tv and television. Synonyms should be treated as a business rule, not as a universal fix for poor product data.
For stable synonym lists, define a synonym filter in the index settings. For frequently changing lists, consider a synonym graph filter and a controlled reload strategy appropriate to the Elasticsearch version and deployment model. Multiword synonyms require particular care because token positions affect phrase queries and relevance.
Decide whether a synonym is equivalent or one-way. An equivalent rule such as sneakers, trainers expands both terms. A one-way rule such as tv => television maps only the customer term to the catalog term. Review synonym changes with merchandising stakeholders, and test them with phrase queries and filters.
Autocomplete is not ordinary full-text search
Edge n-grams can support search-as-you-type behavior, but applying them to every product field increases index size and can produce noisy results. Use a dedicated autocomplete field or consider Elasticsearch's search_as_you_type field type when it fits the application.
Keep the autocomplete search analyzer simple. If a query such as sho is stemmed, expanded with broad synonyms, or processed with an incompatible tokenizer, matching may become surprising. Measure index growth and query latency with a realistic catalog, including variable products and long titles.
Language, accents, and multiple storefronts
Multilingual WooCommerce stores should not assume that one analyzer works equally well for every language. Stemming, stop words, tokenization, and compound-word handling vary significantly. German compounds, French accents, and languages without whitespace boundaries may require different analyzers or separate language-specific fields.
Possible designs include separate fields such as name.en and name.fr, separate indices per storefront, or a language field that selects the appropriate query logic. The correct choice depends on catalog size, language detection reliability, and whether users search across languages.
Accent handling can be implemented with an asciifolding token filter. Decide whether to preserve the original token. Preserving it can support exact display-sensitive behavior while also adding an ASCII-compatible term, but it increases the term set. Test names and brands where accents are meaningful.
Analyzer changes require an index migration
Most analyzer settings are fixed when an index is created. Changing an analyzer for an existing field normally requires creating a new index and reindexing the documents. For WooCommerce, use an alias-based migration rather than changing production search behavior manually.
- Create a versioned index such as
products-v3with the new settings and mappings. - Reindex products from the source of truth or from the existing index.
- Replay or synchronize product updates that occurred during the migration.
- Run relevance, autocomplete, filtering, and performance tests.
- Point the read alias to the new index atomically.
- Retain the previous index temporarily for rollback, then remove it according to the retention policy.
When products change frequently, coordinate the migration with WooCommerce webhooks, an integration queue, or another durable update mechanism. A reindex that ignores stock, price, visibility, or variation updates can produce correct tokens but stale shopping results.
Testing checklist for agencies
- Use the Analyze API to inspect index-time and search-time tokens.
- Test exact SKU queries, partial SKU queries, product names, brands, attributes, and misspellings separately.
- Verify that numeric values such as sizes, voltages, capacities, and model years are preserved where necessary.
- Measure result quality for singular and plural queries, synonyms, accents, and punctuation variants.
- Check phrase queries after adding stemming, stop words, or synonyms.
- Benchmark index size, indexing throughput, and search latency using a production-sized catalog.
- Validate that filters, sorting, aggregations, and exact matches use keyword fields rather than analyzed text fields.
- Document every analyzer, token filter, synonym source, and reindex procedure with the index version.
Analyzers should be designed around the way shoppers search and the way the catalog is maintained. Separating natural-language fields from identifiers, using dedicated autocomplete fields, inspecting tokens with the Analyze API, and deploying changes through versioned indices gives WooCommerce teams a reliable foundation for relevance work.