Search quality in a WooCommerce catalog depends heavily on how product text is analyzed at index time and query time. The default analyzer is a useful starting point, but agencies often need different behavior for product names, descriptions, brand names, SKUs, and merchandising terms.
What an analyzer does
An Elasticsearch analyzer converts text into the terms that are stored in the inverted index. An analyzer can contain three stages:
- Character filters: Modify the original text before tokenization, such as removing HTML markup or replacing selected characters.
- Tokenizer: Splits the resulting text into tokens.
- Token filters: Normalize or transform tokens, for example by lowercasing, removing stop words, applying stemming, or generating autocomplete prefixes.
For example, the product name Men’s Running-Shoes, Size 10 might be converted into terms such as mens, running, shoes, and size, depending on the configured tokenizer and filters.
Separate analysis by catalog field
A product catalog rarely benefits from one analyzer for every field. Product descriptions generally need natural-language processing, while SKUs and model numbers usually need exact or structured matching. Use multi-fields when the same value needs both full-text and exact-search behavior.
{
"mappings": {
"properties": {
"name": {
"type": "text",
"analyzer": "product_text",
"search_analyzer": "product_search",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
},
"sku": {
"type": "text",
"analyzer": "sku_index",
"search_analyzer": "sku_search",
"fields": {
"keyword": {
"type": "keyword"
}
}
}
}
}
}
The exact field names should match the document structure produced by the WooCommerce indexing integration. If the integration writes product titles under post_title or stores SKU values inside a nested metadata object, apply the mapping to those actual paths.
Example product analyzers
The following index settings define an analyzer for general product text and a separate pair for SKU values. The product analyzer removes HTML, normalizes case, and creates word tokens. The SKU analyzer preserves useful separators while allowing case-insensitive matching.
{
"settings": {
"analysis": {
"char_filter": {
"sku_separator_normalizer": {
"type": "mapping",
"mappings": [
"- => ",
"_ => "
]
}
},
"filter": {
"product_edge_prefixes": {
"type": "edge_ngram",
"min_gram": 2,
"max_gram": 20
}
},
"analyzer": {
"product_text": {
"type": "custom",
"char_filter": ["html_strip"],
"tokenizer": "standard",
"filter": ["lowercase", "asciifolding"]
},
"product_search": {
"type": "custom",
"char_filter": ["html_strip"],
"tokenizer": "standard",
"filter": ["lowercase", "asciifolding"]
},
"sku_index": {
"type": "custom",
"char_filter": ["sku_separator_normalizer"],
"tokenizer": "whitespace",
"filter": ["lowercase", "asciifolding", "product_edge_prefixes"]
},
"sku_search": {
"type": "custom",
"char_filter": ["sku_separator_normalizer"],
"tokenizer": "whitespace",
"filter": ["lowercase", "asciifolding"]
}
}
}
}
}
The edge_ngram filter is intentionally used only by sku_index. Applying it to the search analyzer would turn a user query into prefixes and can produce unexpected matching behavior. For normal product text, autocomplete is usually better implemented as a dedicated subfield rather than changing the main relevance field.
Autocomplete without damaging relevance
Create a separate analyzed field for search-as-you-type behavior. This lets the primary product name field continue to rank complete words normally while the autocomplete field supports partial input such as run matching running.
{
"settings": {
"analysis": {
"filter": {
"product_autocomplete_filter": {
"type": "edge_ngram",
"min_gram": 2,
"max_gram": 20
}
},
"analyzer": {
"product_autocomplete_index": {
"type": "custom",
"tokenizer": "standard",
"filter": ["lowercase", "asciifolding", "product_autocomplete_filter"]
},
"product_autocomplete_search": {
"type": "custom",
"tokenizer": "standard",
"filter": ["lowercase", "asciifolding"]
}
}
}
},
"mappings": {
"properties": {
"name": {
"type": "text",
"analyzer": "product_text",
"fields": {
"autocomplete": {
"type": "text",
"analyzer": "product_autocomplete_index",
"search_analyzer": "product_autocomplete_search"
}
}
}
}
}
}
When querying, boost the normal name field more highly than the autocomplete field. This prevents a short prefix match from outranking an exact or near-exact product name.
{
"query": {
"multi_match": {
"query": "running shoe",
"fields": [
"name^4",
"name.autocomplete^1.5",
"description"
]
}
}
}
Handling SKUs, model numbers, and dimensions
Do not apply stemming or broad stop-word removal to identifiers. Values such as AB-123, XL-2000, and 12V-5A carry meaning in their individual characters and separators. Index a keyword representation for exact filters and a text representation only when partial or normalized matching is required.
For exact SKU filtering in WooCommerce, use the keyword field:
{
"query": {
"term": {
"sku.keyword": "AB-123"
}
}
}
If shoppers commonly omit hyphens, normalize both the indexed value and the query consistently. A char filter can replace separators with spaces, but it does not remove every possible formatting variation. For more controlled behavior, normalize SKU values in the indexing pipeline and store the normalized value in a dedicated field such as sku_normalized.
Stop words, stemming, and synonyms
Natural-language filters should be selected from real catalog and query data. Stop words can remove meaningful retail terms such as for, pro, or one, especially in branded product names. Test the effect before adding a stop filter.
Stemming can improve recall for ordinary descriptive text, but it may produce undesirable matches for technical terms and brand names. A common approach is to use a stemmed field for descriptions while keeping names and brands on a less aggressive analyzer.
Synonyms require particular care. If synonyms are managed through a synonym set or a synonym filter, use a search-time filter where possible so that synonym changes do not require reindexing every product. Use synonym_graph for multi-word search synonyms and verify that the chosen filter configuration is compatible with the Elasticsearch version used by the agency’s deployment.
Test analyzers before reindexing WooCommerce data
Use the Analyze API with representative catalog values, including HTML descriptions, accented words, punctuation, SKUs, dimensions, and branded terms.
POST products-v2/_analyze
{
"analyzer": "product_text",
"text": "Men's Café Running-Shoes, size 10"
}
Inspect the returned tokens and confirm that the results support the intended queries. Also test the search analyzer separately:
POST products-v2/_analyze
{
"analyzer": "product_search",
"text": "cafe running shoes"
}
The indexed and search analyzers do not need to produce identical token streams, but they must produce compatible terms. An autocomplete index analyzer should generate prefixes while its search analyzer should generally emit the complete user input without prefixes.
Deployment considerations for agencies
- Create a new index: Analyzer and mapping changes generally require a new index and reindexing. Treat analyzer definitions as versioned deployment configuration.
- Use an alias: Index the rebuilt catalog into a versioned index such as
products-2025-01, validate it, and move the read alias atomically. - Keep WooCommerce synchronization safe: During a rebuild, account for products created, updated, unpublished, or deleted after the initial bulk import. Use the integration’s change queue or replay mechanism where available.
- Compare search metrics: Track zero-result searches, click-through rate, add-to-cart rate, and exact SKU lookup success before and after the analyzer change.
- Document field contracts: Record which fields are analyzed, which are keyword-only, and which analyzer is expected by each query template.
For a WooCommerce agency, the safest pattern is usually a conservative analyzer on names and brands, a more linguistic analyzer on descriptions, exact keyword fields for filtering, and dedicated autocomplete fields for partial input. This separation makes relevance tuning possible without forcing one analyzer to serve incompatible catalog use cases.