Autocomplete is a small WooCommerce feature with a large effect on product discovery. Shoppers expect useful suggestions after entering only a few characters, while agencies need those suggestions to be fast, relevant, localized, and safe to operate at scale. Vespa is a good fit when autocomplete must combine prefix matching with product metadata such as popularity, brand, category, stock status, or commercial priority.
Choose the right autocomplete model
There are two common designs:
- Product autocomplete: return matching products with an image, price, stock state, and product URL.
- Query suggestions: return phrases such as “wireless keyboard” or “running shoes” that can be submitted as a normal store search.
A WooCommerce implementation can use both. Product autocomplete is usually generated from the product catalog, while query suggestions can be generated from curated terms, product names, categories, brands, and approved search analytics. Do not expose raw customer queries without filtering them first.
Model suggestions as dedicated Vespa documents
A separate suggestion document type keeps autocomplete traffic independent from the full product search ranking logic. A typical document contains the visible suggestion text and numeric signals used for ranking.
schema product_suggestion {
document product_suggestion {
field suggestion type string {
indexing: index | summary
}
field suggestion_lower type string {
indexing: attribute | summary
}
field popularity type int {
indexing: attribute | summary
}
field priority type int {
indexing: attribute | summary
}
field product_id type int {
indexing: attribute | summary
}
field in_stock type bool {
indexing: attribute | summary
}
}
fieldset default {
fields: suggestion
}
rank-profile autocomplete {
first-phase {
expression: nativeRank(suggestion) +
0.15 * log(1 + attribute(popularity)) +
0.5 * attribute(priority) +
if(attribute(in_stock), 0.25, -1.0)
}
}
}
The suggestion field is indexed for text matching. The attributes are available to ranking and filtering without requiring a document summary fetch. In a production schema, use the exact field types and ranking expression that match the Vespa version and deployment conventions used by your agency.
Use prefix matching for the request
Autocomplete should normally match the final incomplete token as a prefix. For example, “wire key” should find “wireless keyboard” even though the shopper has not finished typing the second word. Vespa supports this through the prefix annotation on the user input query item.
select * from sources product_suggestion
where suggestion contains ({ "prefix": true }userInput(@q))
Send the query text separately from the YQL statement and select the autocomplete ranking profile:
curl --get 'https://search.example.com/search/' \
--data-urlencode 'yql=select * from sources product_suggestion where suggestion contains ({ "prefix": true }userInput(@q))' \
--data-urlencode 'input.query(q=wire key)' \
--data-urlencode 'ranking=autocomplete' \
--data-urlencode 'hits=8'
Verify the exact query syntax against the Vespa version used by the application and test multi-word behavior with real catalog data. Prefix matching is intentionally different from fuzzy matching: it is predictable and fast, but it will not correct a misspelling such as “keybord.” A useful design often uses prefix autocomplete first and offers a separate spell-correction or full-search path after submission.
Build the feed from WooCommerce
Do not query WooCommerce or WordPress synchronously for every keystroke. Export suggestion documents when products, terms, or merchandising rules change. The feed can be driven by WooCommerce webhooks, a scheduled incremental job, or the same event pipeline used to update the product search index.
- Read published, searchable products from WooCommerce.
- Remove products that are private, deleted, hidden from catalog search, or outside the current channel.
- Create normalized suggestion records for product names, brands, categories, and approved aliases.
- Set popularity from a defined window of sales, clicks, or searches rather than an unbounded lifetime count.
- Send document updates and deletes to Vespa in batches.
For a product-level response, store the product identifier in product_id and fetch only the fields needed by the suggestion UI. For a phrase-level response, use a dedicated identifier such as a stable hash of the normalized phrase and omit product-specific fields.
Ranking and merchandising considerations
Text relevance should be the first signal. Popularity and editorial priority should break ties rather than overpower an exact or highly relevant prefix match. A common ranking strategy is:
- Prefer suggestions that match more of the typed input.
- Use a logarithmic popularity feature so high-volume products do not dominate every result.
- Apply a small boost to in-stock products, but decide whether backorders should remain eligible.
- Use an explicit priority attribute for seasonal campaigns and curated synonyms.
- Filter by store, language, currency, channel, or customer segment when those dimensions are part of the catalog.
If the same suggestion exists in several languages, include a locale field and filter it at query time. If a multisite WooCommerce installation has different catalogs, include the site or catalog identifier in the document and apply a mandatory filter. Do not rely on ranking alone to enforce catalog isolation.
Keep the browser request inexpensive
The frontend should wait until the shopper has entered at least two or three characters, debounce requests by roughly 100–250 milliseconds, cancel stale requests, and cap the response to a small number of hits. Cache common prefixes at the edge or application layer when the catalog is relatively stable. A typical request flow is:
let timer;
let controller;
function requestSuggestions(value) {
clearTimeout(timer);
if (value.trim().length < 2) return;
timer = setTimeout(async () => {
if (controller) controller.abort();
controller = new AbortController();
const url = '/wp-json/store/v1/autocomplete?q=' +
encodeURIComponent(value.trim());
const response = await fetch(url, { signal: controller.signal });
const suggestions = await response.json();
renderSuggestions(suggestions);
}, 150);
}
A WordPress REST endpoint is useful as a controlled proxy. It can validate input, add the appropriate tenant and locale filters, hide Vespa credentials, enforce rate limits, and return a stable response shape to the theme or headless storefront. Never allow the browser to submit arbitrary YQL or ranking parameters.
Operational checks for agencies
- Measure p50, p95, and p99 autocomplete latency separately from full search latency.
- Track zero-result prefixes, click-through rate, selection rate, and abandoned requests.
- Monitor feed lag so newly published products become eligible within the promised service level.
- Test prefixes containing accents, punctuation, hyphens, multiple spaces, and non-Latin scripts.
- Confirm that unpublished products, restricted products, and out-of-stock products follow the store’s visibility rules.
- Use bounded result sizes and request timeouts so a slow search service cannot block checkout or navigation.
Autocomplete is most maintainable when it has its own Vespa document type, ranking profile, feed, and API contract. That separation lets an agency tune suggestion relevance and merchandising without destabilizing the main WooCommerce product search experience.