WooCommerce product search usually has two competing goals: match what the shopper typed and present products that are commercially useful. Text relevance identifies products that satisfy the query, while business signals such as sales velocity, margin, inventory, rating, and conversion rate help decide the order among relevant products.
Vespa is well suited to this problem because text matching and business logic can be expressed in the same ranking pipeline. The important design principle is to let relevance establish a minimum level of usefulness before business signals influence the final order.
Separate matching from ordering
A product can have excellent sales numbers and still be a poor result for a specific query. For example, a popular blue running shoe should not rank first for a query such as leather office boots merely because it sells well.
A practical search design separates the problem into two questions:
- Does the product match the query? Use fields such as the product name, SKU, categories, attributes, and description.
- How should matching products be ordered? Use business signals such as popularity, stock status, conversion rate, freshness, and profit margin.
In Vespa, the first question is handled by matching and an initial ranking phase. The second question is handled by a first-phase or second-phase ranking expression, depending on the amount of computation required.
Model the WooCommerce product data for ranking
Business signals should be stored as typed document fields, normally as attributes when they are used frequently in ranking. Attributes are efficient for numeric lookups and ranking calculations.
field popularity_score type double {
indexing: attribute | summary
}
field conversion_rate type double {
indexing: attribute | summary
}
field gross_margin type double {
indexing: attribute | summary
}
field inventory_count type int {
indexing: attribute | summary
}
field updated_at type long {
indexing: attribute | summary
}
field title type string {
indexing: index | summary
}
field description type string {
indexing: index | summary
}
The exact fields depend on the WooCommerce data available to the agency. A product feed might populate popularity_score from normalized order counts, conversion_rate from views and purchases, and gross_margin from the product or variation margin.
Do not send raw values with incompatible scales directly into a ranking expression. A product with 50,000 historical views could overwhelm a relevance score that is usually between zero and ten. Normalize or transform business values during ingestion, or use bounded functions in the ranking expression.
Start with a strong text-relevance baseline
Product search commonly benefits from giving the product name more importance than the long description. A fieldset can combine searchable fields while the rank profile controls their relative contribution.
fieldset default {
fields: title, description
}
rank-profile text_relevance {
first-phase {
expression: 2 * bm25(title) + bm25(description)
}
}
This is an illustrative baseline rather than a universal formula. Many stores should also index SKU, brand, category, and structured attributes separately. Exact SKU matches, for example, may deserve a dedicated field or a separate query branch rather than relying only on general full-text matching.
Add bounded business signals
Once text relevance is working, business signals can be added in a controlled way. A simple approach is to apply logarithmic or bounded transformations so that large values have diminishing influence.
rank-profile commerce_relevance inherits text_relevance {
function business_score() {
expression: 0.45 * normalizedPopularity +
0.25 * normalizedConversion +
0.20 * normalizedMargin +
0.10 * stockAvailability
}
function normalizedPopularity() {
expression: log(1 + popularity_score) / 10
}
function normalizedConversion() {
expression: conversion_rate
}
function normalizedMargin() {
expression: gross_margin
}
function stockAvailability() {
expression: if(inventory_count > 0, 1, 0)
}
first-phase {
expression: 2 * bm25(title) + bm25(description) + business_score()
}
}
The field ranges in this example must be defined consistently. For instance, conversion_rate and gross_margin might be stored between zero and one, while popularity_score may be normalized during the WooCommerce export. If the values are not normalized, the weights do not have a predictable meaning.
In production, a multiplicative formulation can sometimes be safer than a large additive boost. For example, business quality can act as a modest multiplier on a relevance score:
first-phase {
expression: (2 * bm25(title) + bm25(description)) *
(0.85 + 0.15 * business_score())
}
This keeps business signals from turning a weak text match into a top result. The multiplier should remain close to one unless the business requirement explicitly calls for stronger merchandising control.
Use stock as a rule when necessary
Inventory is often different from popularity or margin. A store may want out-of-stock products removed entirely, demoted below available products, or retained for SEO and back-in-stock discovery.
If unavailable products must never appear in a normal shopping search, use a query filter:
where inventory_count > 0
If they may appear but should be demoted, incorporate availability into ranking. Be explicit about the desired behavior because a ranking penalty does not guarantee that an out-of-stock item will disappear when all available items have poor text matches.
Keep query intent in the ranking calculation
Business signals should not be identical for every query. A shopper searching for new arrivals may benefit from freshness, while a shopper searching for a specific SKU needs exact matching. Query parameters can allow the application to select a ranking profile or adjust a controlled weighting.
rank-profile query_aware inherits commerce_relevance {
first-phase {
expression: 2 * bm25(title) +
bm25(description) +
query(business_weight) * business_score()
}
}
The application can send a bounded value for business_weight based on the search experience being used. For example, a category landing page might use a higher value than a strict SKU lookup. Keep this value server-controlled or validate it at the API boundary so clients cannot arbitrarily manipulate ranking.
Another option is to use separate rank profiles such as exact_lookup, standard_search, and merchandising_search. This is often easier to test and explain than exposing many independent ranking parameters.
Use multiple ranking phases for expensive signals
Text relevance and inexpensive numeric attributes can usually be evaluated for a large candidate set. More expensive logic should be reserved for a later phase after Vespa has reduced the candidate set.
For example, first phase can combine BM25 with basic popularity and availability. Second phase can apply a more detailed formula involving several signals or a machine-learned model.
rank-profile commerce_two_phase inherits text_relevance {
first-phase {
expression: 2 * bm25(title) +
bm25(description) +
0.2 * log(1 + popularity_score)
}
second-phase {
expression: 0.65 * firstPhase +
0.15 * conversion_rate +
0.10 * gross_margin +
0.10 * stockAvailability()
rerank-count: 200
}
function stockAvailability() {
expression: if(inventory_count > 0, 1, 0)
}
}
The precise Vespa configuration syntax and available ranking features should be validated against the deployed Vespa version. The architectural principle remains the same: retrieve and score a broad candidate set cheaply, then rerank a limited number of candidates with more complex business logic.
Handle freshness without making products unstable
Freshness is useful for campaigns, seasonal catalogs, and stores where new products are strategically important. A hard preference for recent products can make search results fluctuate too frequently, so use a decay function or a small bounded contribution.
function freshness_score() {
expression: if(age(timestamp, updated_at) < 86400, 1,
if(age(timestamp, updated_at) < 604800, 0.5, 0.1))
}
In practice, the ingestion process should define whether updated_at means product creation time, a meaningful catalog update, or any WooCommerce edit. If every minor price or stock update changes the timestamp, freshness will reflect data synchronization activity rather than product recency.
Test relevance and commercial outcomes separately
Combining signals makes evaluation more important. A ranking change can improve revenue while reducing search quality, or improve text relevance while lowering conversion. Track both types of metrics.
- Relevance metrics: judged relevance, zero-result rate, reformulation rate, click position, and success on exact product or SKU queries.
- Commerce metrics: add-to-cart rate, conversion rate, revenue per search, margin per search, and out-of-stock exposure.
- Operational metrics: query latency, document freshness, ranking-profile usage, and the percentage of results affected by each business signal.
Create test queries that expose conflicts between signals. A useful test set includes specific product names, generic category queries, misspellings, brand searches, SKU searches, queries for unavailable products, and queries where a high-margin product is less textually relevant than a lower-margin alternative.
Make ranking explainable during development
When a merchant asks why one product outranks another, the team should be able to inspect both text and business components. Return or log ranking features during development, and compare values for representative products.
A useful diagnostic record includes:
- The active rank profile.
- BM25 contributions for each important text field.
- Popularity, conversion, margin, inventory, and freshness values.
- The final first-phase and second-phase scores.
- The query classification or merchandising mode used by the application.
Do not treat the final score as an explanation by itself. A score is only useful when the team can decompose it into the factors that produced it.
Recommended implementation sequence
- Build and evaluate a text-only profile using realistic WooCommerce queries.
- Add stock handling as an explicit filter or controlled ranking penalty.
- Normalize popularity, conversion, margin, and freshness values.
- Add one business signal at a time and measure its effect.
- Use bounded weights so no single signal dominates unexpectedly.
- Move expensive calculations into a second ranking phase when needed.
- Compare ranking changes against both relevance and commerce metrics.
- Expose ranking diagnostics to the agency team and merchandisers.
For WooCommerce agencies, this approach provides a repeatable way to add merchandising intelligence without sacrificing query intent. Text relevance finds plausible products; carefully normalized business signals decide which relevant products deserve greater visibility.