Table of contents :

Brands, Product Codes and Exact Matching

100-days-of-weaviate-030

Table of contents :

WooCommerce search often needs two different kinds of relevance. A shopper may search for “waterproof hiking jacket” and benefit from semantic similarity, while an agency operator searching for SKU-48392-BLK-M expects one exact product. Brand names and product codes should therefore not be treated like ordinary descriptive text.

Why exact matching matters in WooCommerce

Product codes, SKUs, manufacturer part numbers, EANs, UPCs, and internal identifiers are usually short, structured values. A vector search can return a semantically similar product instead of the product represented by the code. That is unacceptable for stock lookups, product feeds, customer-service tools, and order-management workflows.

Brand names have a similar problem. A search for ACME should not automatically rank products from ACME Outdoor, ACME Accessories, or a misspelled brand above the canonical brand unless that behavior is explicitly intended.

Store exact-match fields separately

Do not rely on the product title alone. During synchronization from WooCommerce, create dedicated properties for values that have an exact or near-exact business meaning.

  • skuExact: the normalized WooCommerce SKU.
  • brandExact: the canonical brand value or a stable brand identifier.
  • mpnExact: the manufacturer part number.
  • eanExact and upcExact: identifiers stored as strings, not numbers.
  • skuDisplay and brandDisplay: the original formatting shown to customers.

Keep identifiers as strings because leading zeroes, hyphens, slashes, and letter casing can be significant. For example, 001245 must not become the numeric value 1245.

Normalize without destroying the original value

A useful integration stores both the display value and a comparison value. A normalization function might trim whitespace, convert letters to a consistent case, and apply a documented policy for separators.

function normalizeCode(value) {
  return String(value ?? '')
    .normalize('NFKC')
    .trim()
    .toUpperCase()
    .replace(/[\s-]+/g, '');
}

const product = {
  skuDisplay: productFromWoo.sku,
  skuExact: normalizeCode(productFromWoo.sku),
  brandDisplay: productFromWoo.brand,
  brandExact: normalizeCode(productFromWoo.brand)
};

Separator removal is not universally correct. If a manufacturer distinguishes AB-12 from AB12, preserve the separator in the exact key and create a separate normalized alias only when the business rules permit it. The normalization policy must be shared by the WooCommerce importer and the search endpoint.

Use Weaviate properties deliberately

For exact-oriented text properties, configure a tokenization strategy that does not split the value into ordinary word tokens. The field tokenization option treats the complete property value as one token, which is useful for identifiers and controlled values. A typical collection definition can include a text property such as:

"properties": [
  {
    "name": "skuExact",
    "dataType": ["text"],
    "tokenization": "field",
    "indexSearchable": true,
    "indexFilterable": true
  },
  {
    "name": "brandExact",
    "dataType": ["text"],
    "tokenization": "field",
    "indexSearchable": true,
    "indexFilterable": true
  }
]

The exact configuration syntax depends on the Weaviate client and server version. Verify the supported property options for the version used by the agency. The important design is that exact-match fields are distinct from long-form searchable fields such as title, description, and searchText.

Prefer filters for deterministic identifiers

When a request looks like a SKU or another known identifier, perform a deterministic lookup using a filter instead of asking vector search to infer the result. In the current Weaviate client APIs, the operation is conceptually equivalent to:

const result = await products.query.fetchObjects({
  filters: products.filter.byProperty('skuExact').equal(normalizeCode(input)),
  limit: 5,
  returnProperties: ['skuDisplay', 'name', 'brandDisplay', 'woocommerceId']
});

If the integration uses GraphQL or an older client, the same rule can be expressed with a where filter on skuExact. Check the returned object count and handle duplicate values as a data-quality error. A SKU intended to be unique should have a unique constraint in the synchronization process, even if the vector database itself does not enforce relational uniqueness.

Combine brand filters with semantic search

Brand selection is often a filter, while the product phrase is semantic. For example, “lightweight trail shoes” can be searched with a near-text or hybrid query while restricting results to a canonical brand.

const result = await products.query.hybrid('lightweight trail shoes', {
  filters: products.filter.byProperty('brandExact').equal('ACME'),
  limit: 20,
  returnProperties: ['name', 'brandDisplay', 'skuDisplay', 'price']
});

This prevents unrelated brands from entering the candidate set. If the user types a brand that is not yet canonical, resolve it first through a brand alias table or a small exact-and-fuzzy brand lookup. Do not silently convert an ambiguous value into a filter.

Use a routing strategy for search requests

A production WooCommerce search service can route requests in stages:

  1. Detect an identifier. Check for a SKU, MPN, EAN, UPC, or a code-like query pattern.
  2. Normalize the candidate. Apply the same normalization used during indexing.
  3. Run an exact filter. Return the matching product or products when the identifier is authoritative.
  4. Resolve controlled terms. Match a brand against canonical names and approved aliases.
  5. Run hybrid or vector search. Use semantic and keyword relevance for the remaining descriptive query.
  6. Apply business rules. Exclude unpublished products, out-of-scope stores, or products unavailable to the customer.

This routing avoids wasting vector-search capacity on a lookup that can be answered by an indexed filter. It also makes the response easier to explain to support staff: the product matched because its normalized SKU was equal to the supplied code, not because it happened to be semantically similar.

Handle variants and multi-store catalogs

WooCommerce data frequently contains parent products and variations. Decide whether the identifier belongs to the parent, the variation, or both. A variation SKU should normally index to a variation-level object so that stock, price, attributes, and purchase links remain accurate.

For agencies managing multiple stores, include a tenant or site property and combine it with the exact filter:

const filter = products.filter.allOf([
  products.filter.byProperty('siteId').equal('store-eu'),
  products.filter.byProperty('skuExact').equal('AB123BLACKM')
]);

Apply tenant filtering to every query path, including exact lookups. A correct SKU from another store is still the wrong result for the current storefront.

Test exactness as a data contract

Include automated tests for case differences, whitespace, separators, leading zeroes, Unicode normalization, duplicate SKUs, variation SKUs, and brand aliases. Test both the importer and the API endpoint with the same fixtures.

  • ab-123 follows the documented relationship to AB123.
  • 00123 remains distinct from 123 when leading zeroes matter.
  • An exact SKU query does not return a product with a merely similar SKU.
  • A brand filter does not match a different canonical brand because it shares a token.
  • A deleted or unpublished WooCommerce product is not returned by an exact lookup.

Use vector and hybrid search for meaning, filters for identity, and explicit normalization for controlled values. Keeping those responsibilities separate produces WooCommerce search behavior that is faster to debug, safer for catalog operations, and more predictable for customers.

Trending posts
You might also like