Guide for building catalog and e-commerce search with Elasticsearch. Use when a developer wants product search, faceted navigation, autocomplete, "did you mean" suggestions, or shopping-oriented search experiences.
Guide for building catalog and e-commerce search with Elasticsearch. Use when a developer wants product search, faceted navigation, autocomplete, "did you mean" suggestions, or shopping-oriented search experiences.
Catalog / E-Commerce Search Guide
Guide developers through building product catalog and e-commerce search with Elasticsearch. Use this guide when they need product search with filtering, faceting, autocomplete, boosting by attributes, and shopping-oriented relevance.
Conversation flow — return to onboarding
This skill provides deep implementation detail for catalog and e-commerce search. It is not the main conversation driver.
After applying the guidance here, re-read /elasticsearch-onboarding to resume the structured onboarding playbook (Steps 1–7: intent → data → mapping → build → test → iterate). That playbook controls sequencing, the one-question-at-a-time rule, and the Dev Tools API-snippet workflow. If /elasticsearch-onboarding has not been loaded yet in this conversation, load it now — it is the primary conversation flow for all Elasticsearch search onboarding.
1. When to Use This Guide
Apply this guide when the developer signals:
Product search — search across a product catalog with titles, descriptions, categories
Faceted navigation — filter by brand, category, price range, rating, with counts
Autocomplete / typeahead — suggest products as the user types
"Did you mean" — spelling correction and suggestions
Merchandising / boosting — promote certain products (new arrivals, on sale, high margin)
Do not use this guide when: the developer only needs document search without structured attributes — point them to keyword-search or vector-hybrid-search. If they need meaning-based "find similar products," combine this with the vector-hybrid-search approach.
2. Index Mapping
E-commerce indices need text fields for search, keyword fields for filtering/faceting, numeric fields for sorting/range filters, and nested fields for variants.
PUT /products
{"settings":{"analysis":{"analyzer":{"autocomplete_analyzer":{"type":"custom","tokenizer":"standard","filter":["lowercase","autocomplete_filter"]},"synonym_analyzer":{"type":"custom","tokenizer":"standard","filter":["lowercase","product_synonyms"]}},"filter":{"autocomplete_filter":{"type":"edge_ngram","min_gram":2,"max_gram":15},"product_synonyms":{"type":"synonym","synonyms":["laptop, notebook => laptop","phone, mobile, cell phone => phone","tv, television => tv","headphones, earphones, earbuds => headphones"]}}}},"mappings":{"properties":{"title":{"type":"text","analyzer":"synonym_analyzer","fields":{"keyword":{"type":"keyword"},"autocomplete":{"type":"text","analyzer":"autocomplete_analyzer","search_analyzer":"standard"}}},"description":{"type":"text","analyzer":"synonym_analyzer"},"category":{"type":"keyword"},"subcategory":{"type":"keyword"},"brand":{"type":"keyword"},"price":{"type":"float"},"sale_price":{"type":"float"},"currency":{"type":"keyword"},"rating":{"type":"float"},"review_count":{"type":"integer"},"in_stock":{"type":"boolean"},"sku":{"type":"keyword"},"tags":{"type":"keyword"},"image_url":{"type":"keyword","index":false},"created_at":{"type":"date"},"popularity_score":{"type":"float"},"attributes":{"type":"nested","properties":{"name":{"type":"keyword"},"value":{"type":"keyword"}}},"title_suggest":{"type":"completion","analyzer":"simple"}}}}
Use _id = SKU so re-indexing updates in place. For large catalogs (>100K products), use bulk batches of 1,000-5,000 documents.
4. Query Patterns
Product Search with Filters
POST /products/_search
{"query":{"bool":{"must":[{"multi_match":{"query":"wireless headphones","fields":["title^3","description","brand^2","tags"],"type":"best_fields","fuzziness":"AUTO"}}],"filter":[{"term":{"in_stock":true}},{"term":{"category":"electronics"}},{"range":{"price":{"gte":50,"lte":300}}}]}},"sort":[{"_score":"desc"},{"popularity_score":"desc"}],"size":20}
Faceted Navigation (Aggregations)
Return filter counts alongside search results:
POST /products/_search
{"query":{"bool":{"must":[{"match":{"title":"headphones"}}],"filter":[{"term":{"in_stock":true}}]}},"size":20,"aggs":{"categories":{"terms":{"field":"category","size":20}},"brands":{"terms":{"field":"brand","size":20}},"price_ranges":{"range":{"field":"price","ranges":[{"to":50,"key":"Under $50"},{"from":50,"to":100,"key":"$50-$100"},{"from":100,"to":200,"key":"$100-$200"},{"from":200,"key":"$200+"}]}},"avg_rating":{"avg":{"field":"rating"}},"rating_distribution":{"histogram":{"field":"rating","interval":1,"min_doc_count":0}}}}
Autocomplete
POST /products/_search
{"suggest":{"product-suggest":{"prefix":"wire","completion":{"field":"title_suggest","size":8,"skip_duplicates":true,"fuzzy":{"fuzziness":"AUTO"}}}}}
For search-as-you-type with results (not just suggestions):
POST /products/_search
{"query":{"match":{"title.autocomplete":{"query":"wire","operator":"and"}}},"size":5,"_source":["title","brand","price","image_url"]}
"Did You Mean" (Spelling Suggestions)
POST /products/_search
{"suggest":{"spelling":{"text":"wireles headphons","phrase":{"field":"title","size":3,"gram_size":3,"direct_generator":[{"field":"title","suggest_mode":"popular"}]}}}}
Boosted Search (Merchandising)
Promote on-sale, highly-rated, or popular products:
POST /products/_search
{"query":{"function_score":{"query":{"multi_match":{"query":"headphones","fields":["title^3","description","brand^2"]}},"functions":[{"field_value_factor":{"field":"rating","modifier":"log1p","factor":2}},{"field_value_factor":{"field":"review_count","modifier":"log1p","factor":0.5}},{"filter":{"exists":{"field":"sale_price"}},"weight":1.5},{"gauss":{"created_at":{"origin":"now","scale":"30d","decay":0.5}}}],"score_mode":"sum","boost_mode":"multiply"}}}
Nested Attribute Filtering
Filter by dynamic product attributes (size, color, material):
POST /products/_search
{"query":{"bool":{"must":[{"match":{"title":"shoes"}}],"filter":[{"nested":{"path":"attributes","query":{"bool":{"must":[{"term":{"attributes.name":"color"}},{"term":{"attributes.value":"red"}}]}}}},{"nested":{"path":"attributes","query":{"bool":{"must":[{"term":{"attributes.name":"size"}},{"term":{"attributes.value":"10"}}]}}}}]}}}
title^3 weights title matches higher than description
Fuzziness
AUTO handles typos; increase for more tolerance
Function score
Boost by rating, recency, popularity, on-sale status
Synonyms
Map domain terms so "laptop" matches "notebook"
Phrase matching
Use match_phrase for exact multi-word queries
7. Common Follow-Ups
Question
Answer
"How do I add sort options?"
Add sort parameter; support price_asc, price_desc, rating, newest.
"How do I show facet counts?"
Use aggregations (terms, range, histogram) alongside your query.
"How do I handle variants (size/color)?"
Use nested fields for attributes; filter with nested queries.
"How do I boost promoted products?"
Use function_score with pinned queries or manual weight boosts.
"How do I handle no results?"
Relax filters, try fuzzy matching, show "did you mean" suggestions, or fall back to popular products.
8. When to Upgrade
Semantic product search — When "comfortable headphones for running" should match even without exact keyword overlap. Add a vector field using the vector-hybrid-search approach.
Hybrid — Combine keyword + semantic for the best of both. See the vector-hybrid-search guide.
Personalization — Boost results based on user behavior (clicks, purchases). Requires a signals index and custom scoring.
