catalog-ecommerce

name	catalog-ecommerce
description	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)
• Multi-attribute filtering — size, color, availability, shipping options

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": 
           
           
           
        
         
           
           
            
            
            
            
          
        
      
    
  
   
     
       
         
         
         
              
                  
        
      
            
          
          
          
          
          
          
          
          
          
          
          
            
          
          
       
         
         
              
              
        
      
       
         
         
      
    
  

3. Ingestion

from elasticsearch import Elasticsearch, helpers

es = Elasticsearch(cloud_id="...", api_key="...")

def index_products(products: list[dict]) -> tuple[int, list]:
    actions = []
    for product in products:
        product["title_suggest"] = {
            "input": [product.get("title", ""), product.get("brand", "")],
            "weight": int(product.get("popularity_score", 1))
        }
        actions.append({"_index": "products", "_id": product.get("sku"), "_source": product})

    return helpers.bulk(es, actions, raise_on_error=False, raise_on_exception=False)

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"     
                   
      
    
  
   
       
       
  
   

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 }
    
     
            
    
     
       
         
         
               
                 
                 
               
        
      
    
     
          
    
     
              
    
  

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": 
             
             
          
        
        
                 
           
        
        
           
             
               
               
               
            
          
        
      
       
       
    
  

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":   
                
              
            
          
        
        
           
             
             
               
                 
                        
                        
                
              
            
          
        
      
    
  

5. API Endpoint

from flask import Flask, request, jsonify
from elasticsearch import Elasticsearch

app = Flask(__name__)
es = Elasticsearch(cloud_id="...", api_key="...")

@app.route("/search", methods=["GET"])
def product_search():
    q = request.args.get("q", "")
    category = request.args.get("category")
    brand = request.args.get("brand")
    min_price = request.args.get("min_price", type=float)
    max_price = request.args.get("max_price", type=float)
    in_stock = request.args.get("in_stock", "true").lower() == "true"
    sort_by = request.args.get("sort", "relevance")
    page = request.args.get("page", 1, type=int)
    size = request.args.get("size", 20, type=int)

    must = []
    if q:
        must.append({
            "multi_match": {
                "query": q,
                "fields": ["title^3", "description", "brand^2", "tags"],
                "type": "best_fields",
                "fuzziness": "AUTO"
            }
        })

    filters = [{: {: in_stock}}]
     category:
        filters.append({: {: category}})
     brand:
        filters.append({: {: brand}})
     min_price   :
        filters.append({: {: {: min_price}}})
     max_price   :
        filters.append({: {: {: max_price}}})

    sort_options = {
        : [{: }, {: }],
        : [{: }],
        : [{: }],
        : [{: }, {: }],
        : [{: }],
    }

    body = {
        : {
            : {
                : must  must  [{: {}}],
                : filters
            }
        },
        : (page - ) * size,
        : size,
        : sort_options.get(sort_by, sort_options[]),
        : {: {: {}, : {}}},
        : {
            : {: {: , : }},
            : {: {: , : }},
            : {: {: }},
            : {
                : {
                    : ,
                    : [
                        {: , : },
                        {: , : , : },
                        {: , : , : },
                        {: , : , : },
                        {: , : }
                    ]
                }
            }
        }
    }

    resp = es.search(index=, body=body)

     jsonify({
        : [{
            : h[],
            : h[],
            : h.get(, {})
        }  h  resp[][]],
        : resp[][][],
        : {
            : [{: b[], : b[]}  b  resp[][][]],
            : [{: b[], : b[]}  b  resp[][][]],
            : [{: b[], : b[]}  b  resp[][][]],
            : resp[][]
        },
        : page,
        : (resp[][][] + size - ) // size
    })


 ():
    q = request.args.get(, )
    resp = es.search(
        index=,
        body={
            : {
                : {
                    : q,
                    : {
                        : ,
                        : ,
                        : ,
                        : {: }
                    }
                }
            }
        }
    )
    suggestions = resp[][][][]
     jsonify({
        : [{: s[], : s[]}  s  suggestions]
    })

6. Relevance Tuning

Lever	Effect
Field boosting	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.