Indexing Product SKUs and Exact Identifiers

Product SKUs, GTINs, MPNs, barcodes, and supplier codes are not ordinary product-search text. Store managers and customers usually expect an identifier lookup to return the product whose identifier matches the input, not products that happen to contain similar words. In Vespa, the cleanest design is to model identifier retrieval separately from descriptive search and make the matching behavior explicit.

Separate identifiers from descriptive content

A WooCommerce product document may contain several identifier fields. A simple product could use the SKU from _sku, while a variable product may expose a parent SKU, variation SKU, GTIN, or manufacturer part number. Do not combine these values into the product title or a general full-text field. Keeping them separate lets the query decide whether an identifier match should be a strict filter, a high-confidence ranking signal, or a fallback search path.

field sku type string {
    indexing: attribute | summary
    attribute: fast-search
    match {
        text: exact
    }
}

field gtin type string {
    indexing: attribute | summary
    attribute: fast-search
    match {
        text: exact
    }
}

field mpn type string {
    indexing: attribute | summary
    attribute: fast-search
    match {
        text: exact
    }
}

The summary index makes the values available in returned documents. The attribute enables efficient filtering and access during ranking. Fast search is useful when an identifier is used as a filter across a large catalog. Confirm the exact field and match configuration against the Vespa version and query patterns used by your deployment, then test it with real catalog values.

Normalize values at ingestion time

WooCommerce data is not always consistent. One feed may contain ABC-123, another may contain abc 123, and a warehouse export may add spaces or punctuation. Decide which differences should be ignored before indexing. A common normalization policy is to trim whitespace, convert letters to uppercase, and remove separators such as spaces and hyphens for a dedicated comparison field.

Keep the original value for display and troubleshooting, but index a normalized field for lookup:

field sku_original type string {
    indexing: summary
}

field sku_normalized type string {
    indexing: attribute | summary
    attribute: fast-search
    match {
        text: exact
    }
}

For example, the displayed SKU can remain ABC-123 while sku_normalized contains ABC123. Apply the same normalization function to the incoming query. Do not silently remove meaningful characters if the merchant uses them to distinguish products. Some businesses treat AB-12 and AB12 as different identifiers, so normalization must be agreed with the catalog owner rather than assumed by the search team.

Use exact matching for identifier queries

When the request is clearly an identifier lookup, query the identifier field directly instead of sending the value through a broad product-text query. With a normalized field, an equality-style filter can be built around the normalized input:

select * from product
where sku_normalized contains "ABC123"

In a production application, construct this query through the Vespa client or query builder and pass the value as a query parameter rather than concatenating untrusted user input into a query string. If your schema uses exact matching on an indexed field, use the corresponding exact-match query syntax and verify that punctuation, case, and tokenization behave as intended.

For a lookup endpoint, an exact identifier match can be treated as a filter:

select * from product
where sku_normalized contains "ABC123"
hits 20

If the normalized SKU is guaranteed to be unique, the application can request one hit and use the result as the product destination. If duplicate SKUs exist across stores, channels, or variations, include the relevant tenant, catalog, or product-type constraint in the filter. Do not rely on ranking to resolve a data-integrity problem.

Combine exact identifiers with normal product search

Not every search box submission is an identifier. A shopper may enter black running shoes, while a warehouse user may enter ABC-123. A practical WooCommerce search service can classify the input before creating the Vespa query:

Normalize the input using the same rules applied during ingestion.
Detect identifier-like patterns, such as a known SKU prefix, a barcode length, or a mixture of letters, digits, and separators.
Run an exact identifier query when the input meets the configured rules.
Fall back to descriptive search when there is no exact identifier result or when the input is ordinary product language.

For a single blended search experience, retain the normal product-text query but give exact identifier matches a decisive rank feature. This lets a query such as ABC-123 return the matching product above products whose descriptions contain related terms. The exact-match signal should be stronger than ordinary title, description, or category relevance.

Index variation identifiers correctly

Variable products require special care. A parent product may have no SKU while each variation has its own SKU. If the search result links to the parent product, return the matching variation identifier in the document or include a variation reference that the WooCommerce application can use to select the correct option.

For agencies, the indexing contract should specify whether one Vespa document represents a parent product, a variation, or both. A variation-oriented document might contain fields such as:

product_id for the WooCommerce parent ID
variation_id for the specific variation
sku_original and sku_normalized
variation attributes such as size, color, or material
availability and channel visibility

If parent and variation documents are both indexed, use a stable document identity and explicit relationship fields. Otherwise, an exact SKU search may return duplicate or incomplete results, especially when a product is visible in multiple sales channels.

Test punctuation, case, and false positives

Identifier tests should be part of the deployment process, not a manual check after release. Include exact values, lowercase input, separator variations, partial values, values with leading zeros, and identifiers that are substrings of other identifiers.

ABC-123 should match the intended product.
abc123 should match only if case normalization is part of the policy.
ABC should not match as an exact SKU unless partial lookup is explicitly supported.
001234 must not be converted to 1234 if leading zeros are significant.
An archived or hidden WooCommerce product should be excluded by the same visibility rules as other searches.

Measure both precision and operational behavior: exact-match success rate, zero-result rate, query latency, and the percentage of identifier searches that fall back to descriptive search. These metrics reveal ingestion defects such as missing variation SKUs, inconsistent normalization, or stale catalog documents.

Keep synchronization and reindexing deterministic

When a WooCommerce administrator changes a SKU, the old identifier must be removed from Vespa as part of the same synchronization workflow. Otherwise, the previous SKU may continue returning a product that no longer owns it. Use event-driven updates where possible, and schedule reconciliation jobs to compare the WooCommerce source of truth with indexed documents.

For bulk imports, generate the normalized identifier fields in one shared transformation library used by webhooks, queue workers, and full reindex jobs. This prevents a product updated through the REST API from receiving different normalization than a product loaded through a nightly feed. Log the original value, normalized value, document ID, and update timestamp so support teams can trace unexpected search results.

Table of contents :