Table of contents :

Understanding BM25 in Vespa

100-days-of-vespa-ai-woocommerce-027

Table of contents :

BM25 is a lexical relevance algorithm that scores how well a document matches the terms in a query. In a WooCommerce search application, it can make product titles, descriptions, attributes, and other indexed fields contribute according to term frequency, document frequency, and field length.

Vespa exposes BM25 as a rank feature. This lets an agency define exactly which product fields participate in BM25 scoring and combine the result with business signals such as inventory, margin, popularity, or product quality.

What BM25 measures

BM25 primarily considers three factors:

  • Term frequency: a term appearing in a document can increase its score, but repeated occurrences have diminishing returns.
  • Inverse document frequency: rare terms contribute more than common terms. A distinctive product model or brand name is therefore more valuable than a term appearing on nearly every product.
  • Document length: BM25 normalizes for field length so that long descriptions do not automatically win simply because they contain more words.

A simplified form of the term contribution is:

idf(term) * ((k1 + 1) * termFrequency) / (k1 * (1 - b + b * fieldLength / averageFieldLength) + termFrequency)

The k1 parameter controls term-frequency saturation, while b controls length normalization. Vespa provides sensible defaults, and most WooCommerce implementations should first evaluate search quality before changing these parameters.

Enabling BM25 for product fields

BM25 must be enabled on the indexed Vespa fields where it will be used. A product schema might contain the following fields:

field title type string {
    indexing: index | summary
    index: enable-bm25
}

field short_description type string {
    indexing: index | summary
    index: enable-bm25
}

field description type string {
    indexing: index | summary
    index: enable-bm25
}

field sku type string {
    indexing: index | summary
    index: enable-bm25
}

The exact field set should reflect the product data model. Product titles and short descriptions are usually strong relevance fields. Long descriptions can add useful recall but may introduce noise. SKUs and model numbers often need a separate exact-match or weighted matching strategy because lexical relevance alone may not express their business importance.

Using BM25 in a rank profile

After enabling BM25, expose it through a rank profile. The following profile uses the title as its primary lexical signal:

rank-profile product_bm25 inherits default {
    first-phase {
        expression: bm25(title)
    }
}

A query can select this profile while using Vespa’s query-language parsing:

/search/?yql=select * from sources * where userQuery();&query=wireless+headphones&ranking=product_bm25

For a multi-field product search, combine the individual BM25 features. Giving the title a larger weight is often appropriate because a matching title is usually more useful than the same term in a long description:

rank-profile product_text inherits default {
    first-phase {
        expression: 4 * bm25(title) + 2 * bm25(short_description) + bm25(description)
    }
}

The multipliers are application-specific, not universal BM25 parameters. Test them against real WooCommerce queries, especially queries containing brands, product types, sizes, colors, and model numbers.

Field weighting and product search behavior

BM25 scores are calculated per field. This makes field selection important. A title match can be promoted by multiplying bm25(title), while a description match can remain a supporting signal.

For example, a query for red running shoes should generally prefer a product whose title contains those terms over a product that mentions them once in a long description. However, a query for a technical model such as WH-1000XM5 may require exact matching, normalization, or a dedicated SKU field in addition to BM25.

Do not assume that increasing the number of repeated terms will proportionally increase relevance. BM25 deliberately saturates term frequency. This prevents keyword stuffing in product descriptions from overwhelming more useful signals.

Combining BM25 with WooCommerce business signals

BM25 measures textual relevance; it does not know whether a product is in stock, profitable, available in a customer’s market, or preferred by a merchandising team. Vespa rank profiles can combine BM25 with document attributes and query features:

rank-profile product_search inherits default {
    inputs {
        query(user_intent_weight): 1.0
    }
    first-phase {
        expression: 5 * bm25(title) + 2 * bm25(short_description) + 0.2 * attribute(popularity)
    }
}

In production, business values should be normalized before they are added to a text score. A raw revenue value, inventory count, or review count can otherwise dominate BM25 unexpectedly. Agencies commonly use a capped or logarithmic popularity feature, and apply hard eligibility rules such as stock or store availability in the query or ranking logic.

A practical separation is:

  • Use query filtering for requirements such as catalog, language, region, visibility, and stock policy.
  • Use BM25 for lexical relevance.
  • Use controlled ranking features for popularity, conversion rate, margin, freshness, and merchandising.

BM25 is not semantic search

BM25 matches terms and their statistics. It will not inherently understand that trainers and sneakers can describe similar products, or that laptop bag and notebook case may express the same intent. Synonym expansion, stemming, normalization, query rewriting, or embeddings can address those cases.

A common Vespa design uses BM25 as a first-stage lexical signal and adds semantic retrieval or ranking for broader intent. The lexical score remains valuable for exact product names, brands, identifiers, and terms that must be visible in the matched document.

Testing and tuning BM25 in an agency project

  1. Collect representative queries from WooCommerce search logs, including zero-result searches and searches that lead to product clicks or purchases.
  2. Create judgments for the products that should appear near the top for each query.
  3. Start with title, short description, and description fields enabled for BM25.
  4. Compare title-only scoring with a weighted multi-field profile.
  5. Inspect cases involving SKUs, spelling variations, synonyms, repeated terms, and very long descriptions.
  6. Measure ranking quality before and after each change rather than tuning from a handful of manual examples.

Vespa can return ranking information for debugging when rank-feature output is requested. Inspect the individual bm25(field) values and the final expression so that a poor result can be attributed to field configuration, query parsing, missing data, or business-signal weighting.

Operational considerations for WooCommerce catalogs

BM25 depends on indexed term statistics. After importing or updating a catalog, verify that the document fields contain the intended analyzed text and that the relevant fields have BM25 enabled. HTML fragments, duplicated descriptions, tracking text, and unfiltered template content can distort field length and term statistics.

Keep identifiers such as SKUs, GTINs, and manufacturer part numbers available in dedicated fields. Use normalized copies where case, punctuation, or formatting differences are common. This allows exact or structured matching to complement, rather than compete unpredictably with, BM25.

For a multi-tenant or multi-store WooCommerce platform, evaluate BM25 per catalog when catalogs have substantially different vocabularies and field lengths. A ranking profile that works for fashion products may not work for spare parts or industrial equipment, even when both use the same Vespa application.

Trending posts
You might also like