Table of contents :

Search-Time vs Index-Time Analysis

100-days-of-elasticsearch-woocommerce-035

Table of contents :

In WooCommerce search, analysis determines how product text is converted into terms that Elasticsearch can store and match. The two important moments are index time, when a document is written to the index, and search time, when a user query is analyzed before matching. Designing these stages deliberately is essential for product names, descriptions, SKUs, attributes, and multilingual catalogs.

What index-time analysis does

Index-time analysis processes a field before its terms are placed in the inverted index. A typical analyzer performs character filtering, tokenization, and token filtering. For example, the text Waterproof Running Shoes might be converted into the terms waterproof, running, and shoes.

Index-time analysis affects what terms are available for future searches. If a transformation removes or changes information, Elasticsearch cannot recover that information during a normal match query. This makes index-time analysis the right place for stable, broadly useful transformations such as lowercasing, language stemming, stop-word handling, and edge n-grams for autocomplete.

Example index analyzer

{
  "settings": {
    "analysis": {
      "analyzer": {
        "product_text_index": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "asciifolding"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "product_text_index"
      }
    }
  }
}

For a WooCommerce product index, this type of analyzer can make searches more tolerant of capitalization and accents. A customer searching for cafe table can match a product containing Café Table.

What search-time analysis does

Search-time analysis processes the user’s query before Elasticsearch executes the query against indexed terms. A query for running shoes may become the terms running and shoes. The resulting terms must be compatible with the terms produced at index time.

Search-time analysis is useful when the query should be interpreted differently from the stored content. Common examples include preserving the original query terms, applying synonyms, removing query-only noise words, and handling user input without changing the index.

Elasticsearch uses the field’s search_analyzer when one is configured. If it is not configured, the field’s index analyzer is normally used for search as well.

Separate index and search analyzers

{
  "settings": {
    "analysis": {
      "filter": {
        "product_edge": {
          "type": "edge_ngram",
          "min_gram": 2,
          "max_gram": 15
        },
        "product_synonyms": {
          "type": "synonym_graph",
          "synonyms": [
            "sneakers, trainers",
            "tv, television"
          ]
        }
      },
      "analyzer": {
        "product_autocomplete_index": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "asciifolding", "product_edge"]
        },
        "product_autocomplete_search": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "asciifolding", "product_synonyms"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "product_autocomplete_index",
        "search_analyzer": "product_autocomplete_search"
      }
    }
  }
}

The edge n-gram filter creates prefixes such as sh, sho, and shoe at index time. The search analyzer does not create n-grams; it analyzes the complete user input and looks for the corresponding indexed prefixes. This is a common pattern for WooCommerce autocomplete.

Why n-grams belong at index time

Autocomplete requires partial terms to exist in the index. If only the search analyzer creates n-grams, a query such as sho will be transformed into multiple fragments, but the index may contain only the complete term shoes. The query and index terms will not align reliably.

Index-time n-grams increase index size and can increase indexing cost. Keep the gram range narrow, use a dedicated autocomplete field, and avoid applying n-grams to long descriptions. A multi-field lets an agency retain a normal full-text field alongside an autocomplete field.

{
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "product_text_index",
        "fields": {
          "autocomplete": {
            "type": "text",
            "analyzer": "product_autocomplete_index",
            "search_analyzer": "product_autocomplete_search"
          },
          "keyword": {
            "type": "keyword",
            "ignore_above": 256
          }
        }
      }
    }
  }
}

Why synonyms usually belong at search time

Search-time synonyms can expand a query without duplicating every synonym term in every indexed document. If sneakers is treated as equivalent to trainers, a customer can find products using either term while the product index remains smaller.

Search-time synonym changes are also easier to manage operationally, although analyzer definitions still need to be updated through the appropriate Elasticsearch configuration or index settings process. Synonym rules should be tested against real WooCommerce queries because equivalent terms are not always interchangeable. For example, a business may decide that jacket and coat are related but should not produce identical results.

Use a synonym_graph filter for multi-word synonyms and phrase-aware matching. Be careful when combining synonyms with stemming, stop words, or language-specific filters. The order of filters can change the meaning of the resulting query.

Exact values should not depend on text analysis

SKUs, variation IDs, brand codes, barcodes, and order-related identifiers usually require exact matching. Map these values as keyword fields rather than relying on a text analyzer.

{
  "properties": {
    "sku": {
      "type": "keyword",
      "normalizer": "lowercase_keyword"
    },
    "variation_id": {
      "type": "keyword"
    }
  }
}

A keyword normalizer can apply limited single-token transformations such as lowercasing and accent folding, but it cannot tokenize a value like a text analyzer. This allows an agency to make SKU matching case-insensitive while preserving the SKU as one exact value.

Using query-level analyzers carefully

A query can override the field’s configured search analyzer with the analyzer parameter. This is useful for a specific query strategy, but it should not be used to compensate for an unsuitable mapping throughout a WooCommerce search implementation.

{
  "query": {
    "match": {
      "name": {
        "query": "wireless headphones",
        "analyzer": "product_autocomplete_search",
        "operator": "and"
      }
    }
  }
}

For most product search requests, configuring analyzer and search_analyzer in the mapping is easier to maintain. Query-level overrides are more appropriate when different endpoints have intentionally different behavior, such as a broad storefront search versus a strict admin SKU lookup.

Testing both stages with the Analyze API

Before changing a production mapping, inspect the terms generated at each stage. The Analyze API can show whether a tokenizer or filter is producing the terms expected by the WooCommerce search experience.

POST products-0001/_analyze
{
  "analyzer": "product_autocomplete_index",
  "text": "Café Running Shoes"
}

POST products-0001/_analyze
{
  "analyzer": "product_autocomplete_search",
  "text": "sneakers"
}

Compare the output with representative product data and real queries. Test singular and plural forms, accents, punctuation, hyphenated SKUs, brand names, attributes, and partial input. Also test zero-result queries, because overly aggressive stemming or synonym expansion can create unexpected matches.

Operational implications for WooCommerce agencies

Most analyzer changes require a new index and reindexing. An existing field’s indexed terms are not rewritten merely because the mapping is edited. Plan analyzer changes as part of an alias-based deployment: create a new index with the revised settings, bulk-index products and variations, validate representative searches, then move the read alias to the new index.

  1. Export or generate a representative catalog containing simple products, variable products, variations, brands, attributes, SKUs, and multilingual content.
  2. Define index-time and search-time analyzers before creating the index.
  3. Use the Analyze API to inspect terms for both product text and customer queries.
  4. Run relevance tests for exact identifiers, normal words, prefixes, synonyms, accents, and misspellings.
  5. Build the new index and reindex from WooCommerce rather than attempting to retrofit existing terms.
  6. Switch the search alias only after query latency, result quality, and zero-result rates have been checked.

The central design rule is to index the information that must be searchable later, while keeping query-time interpretation flexible where possible. For WooCommerce, this commonly means normal text analysis for names and descriptions, dedicated autocomplete fields for prefixes, search-time synonyms for customer vocabulary, and keyword fields for identifiers and filters.

Trending posts
You might also like