Exact Matching for SKUs and Product Codes

SKU and product-code searches are different from ordinary catalog searches. A customer searching for VESPA-GTS-300-RED usually expects one precise product or variation, not products whose descriptions happen to contain parts of that code. In WooCommerce, exact matching is especially important because SKUs often contain hyphens, slashes, numbers, and variant suffixes.

Model SKUs as exact-search fields

Index the WooCommerce SKU as a dedicated Vespa field instead of relying on a general product title or description field. Product variations should receive their own documents when each variation has a distinct SKU and purchasable inventory.

field sku type string {
    indexing: attribute | summary
    match: exact
}

field product_code type string {
    indexing: attribute | summary
    match: exact
}

The match: exact setting makes the field suitable for complete value matching. A query for VESPA-GTS-300-RED will not behave like a full-text search that separately matches VESPA, GTS, or 300. Keep the original value available in a summary field so it can be returned to the WooCommerce integration or displayed in search results.

Normalize values before indexing

Exact matching is only reliable when the indexing and query paths apply the same normalization rules. Decide whether your store treats case, whitespace, and punctuation as significant, then apply that policy consistently.

A common policy is to trim whitespace and compare case-insensitively while preserving meaningful punctuation. For example, these values can normalize to the same lookup value:

vespa-gts-300-red
VESPA-GTS-300-RED
VESPA-GTS-300-RED

Do not remove hyphens or other characters unless the business considers them insignificant. Removing punctuation can create collisions between codes such as AB-123 and AB123. Store the display SKU separately from the normalized lookup value if the original formatting must be preserved.

field sku_normalized type string {
    indexing: attribute | summary
    match: exact
}

The WooCommerce connector should generate sku_normalized using the same function used by the application when it receives a SKU lookup request. This is safer than trying to compensate for inconsistent formatting in the query alone.

Use a strict YQL branch for SKU lookups

For a dedicated SKU endpoint, query the exact field directly. With an exact-match field, the contains operator applies the field’s configured matching behavior rather than treating the value as ordinary prose.

select * from product where sku_normalized contains @sku

Pass the normalized value as the sku query parameter. In production, URL-encode the parameter and use the Vespa query API rather than concatenating untrusted input into a YQL string.

curl 'https://search.example.com/search/?yql=select%20*%20from%20product%20where%20sku_normalized%20contains%20%40sku&sku=vespa-gts-300-red&hits=10'

A SKU lookup should normally be treated as a filter or deterministic retrieval operation. If the business rule says that only one document may match, verify that assumption in the WooCommerce data and alert on duplicates rather than silently choosing the first result.

Separate exact lookup from ordinary search

Search boxes often accept both natural-language queries and product codes. Do not weaken exact SKU behavior by sending every query through the same relevance profile. Use a two-branch strategy:

Detect whether the input resembles a SKU or product code after normalization.
Run an exact SKU query when it does.
Run the normal title, description, category, and attribute search when it does not.
Optionally show exact-code results above full-text results when both branches are evaluated.

For example, red Vespa helmet should use normal text ranking, while VWB-HELMET-RED-L should first attempt an exact lookup. A failed exact lookup can fall back to ordinary search only if that behavior is useful to shoppers; otherwise, return a clear “no product found” response.

Index WooCommerce variations as first-class documents

WooCommerce often stores the parent product and its variations separately. A parent product may have a blank SKU while each variation has a unique SKU. If the search index only contains parent products, exact searches for variation codes will fail even though the products exist in WooCommerce.

Include at least the following fields for variation documents:

document_id or a stable WooCommerce variation identifier
parent_product_id
sku and sku_normalized
variation_attributes, such as size and color
stock_status and purchasability data
product_url that selects or identifies the variation where appropriate

If both a parent and a variation have the same code, define a deterministic rule. Usually, the variation should win for inventory and add-to-cart operations because it represents the purchasable item.

Keep exact results aligned with catalog state

An exact match does not guarantee that the result is currently purchasable. Apply WooCommerce state filters after matching, or include them in the query when the endpoint is intended for shopping results.

select * from product where sku_normalized contains @sku and stock_status contains in_stock

The precise filter representation depends on how the status field is modeled. Boolean and enumerated attributes are generally preferable for filtering because they avoid interpreting status values as free text. Decide whether out-of-stock, private, draft, and catalog-hidden products should be searchable before exposing the endpoint.

Handle synchronization and duplicate detection

Use WooCommerce webhooks or another event-driven integration to update Vespa when products, variations, stock, visibility, or SKUs change. A SKU edit should remove or update the old indexed value; otherwise, an old exact lookup can continue returning a stale document.

During imports, validate uniqueness in the source catalog and report collisions with the normalized value. A useful operational check is to group indexed documents by sku_normalized and alert when a value has more than one active purchasable document. This catches collisions caused by case folding, whitespace trimming, or an accidental duplicate in WooCommerce.

Test the matching contract

Automated tests should cover both positive and negative cases. Verify that the exact value matches, while partial values, token fragments, and unrelated punctuation do not match unless the documented normalization policy says they should.

VESPA-GTS-300-RED matches the intended SKU.
vespa-gts-300-red matches if comparison is case-insensitive.
GTS-300 does not match a complete-SKU field.
VESPA does not match a complete-SKU field.
A retired or hidden variation is excluded when the endpoint requires purchasable products.
Two active products cannot silently share the same normalized SKU.

With a dedicated exact field, consistent normalization, variation-level indexing, and explicit catalog-state rules, Vespa can provide fast deterministic SKU lookups without compromising the relevance of normal WooCommerce product search.

Table of contents :