Table of contents :

Search Across Product Titles, Attributes and Descriptions with Vespa.ai

100-days-of-vespa-ai-woocommerce-025

Table of contents :

Why product search needs more than a title field

WooCommerce catalogs often contain the information a shopper needs in several places. A product title may contain the model name, the description may contain technical specifications, and WooCommerce attributes may contain values such as blue, XL, or stainless steel.

If an agency indexes only the product title, searches for attribute values and descriptive phrases will produce incomplete results. Vespa.ai can search these sources together while still keeping structured attribute values available for filtering, faceting, and ranking.

Use separate fields for separate jobs

A practical product document normally contains both searchable text fields and structured fields. Text fields are suitable for relevance matching. Structured fields are better for exact filters and facets.

schema product {
  document product {
    field product_id type string {
      indexing: summary | attribute
      attribute: fast-search
    }

    field title type string {
      indexing: index | summary
    }

    field description type string {
      indexing: index | summary
    }

    field attribute_text type string {
      indexing: index | summary
    }

    field attribute_values type array<string> {
      indexing: input | attribute
      attribute: fast-search
    }
  }

  fieldset product_text {
    fields: title, description, attribute_text
  }
}

The attribute_text field is a normalized text representation of WooCommerce attributes. For example, a product could contain the following value:

color blue size medium material stainless steel voltage 230v

At the same time, the original values can be stored in attribute_values for exact filtering. Keeping both representations avoids forcing one field to serve two different purposes.

Normalize WooCommerce attributes during ingestion

WooCommerce attributes can be global taxonomies, custom product attributes, or variations. Their names and values should be normalized before they are sent to Vespa. Include the attribute name as well as its value so that a query for a meaningful phrase can match the intended context.

function buildAttributeText(attributes) {
  return attributes
    .filter(attribute => attribute.name && attribute.options)
    .flatMap(attribute => attribute.options.map(option =>
      `${attribute.name} ${option}`
    ))
    .join(' ');
}

For production integrations, also normalize whitespace, HTML entities, casing, and duplicate values. Do not index raw WooCommerce HTML as the only description field. Strip presentation markup while preserving useful text, and keep a separate source or rendering field if the storefront requires the original content.

A document sent to Vespa might look like this:

{
  "fields": {
    "product_id": "4821",
    "title": "Commercial stainless steel blender",
    "description": "High-speed blender for cafes and restaurant kitchens.",
    "attribute_text": "power 1500w capacity 2l material stainless steel color silver",
    "attribute_values": [
      "power:1500w",
      "capacity:2l",
      "material:stainless steel",
      "color:silver"
    ]
  }
}

Search all product text with a fieldset

Define a fieldset containing the title, description, and normalized attribute text. A query using userInput can then search those fields as one logical product-text area.

select * from sources product
where userInput(@query);

The corresponding HTTP request can pass the shopper’s phrase as a query parameter:

GET /search/?yql=select%20*%20from%20sources%20product%20where%20userInput(%40query)&query=stainless%20steel%20blender

When a fieldset is used as the default search area, Vespa applies its linguistic processing and matching behavior consistently across all included fields. This is preferable to building a separate query expression for every combination of title, description, and attribute fields.

Weight titles and attributes differently

Although all three fields should be searchable, they do not necessarily deserve equal influence on ranking. A title match is often a strong signal. A description match is useful but can be broad, while an attribute match may be particularly valuable for specification-driven catalogs.

rank-profile product_text_relevance inherits default {
  first-phase {
    expression: 2.5 * bm25(title) +
                 1.5 * bm25(attribute_text) +
                 1.0 * bm25(description)
  }
}

The correct weights depend on the catalog and should be validated with real search logs. For example, a parts catalog may need stronger attribute weighting than a fashion catalog, where title and category language are more important.

Use a second-phase expression or a business-rank feature when commercial signals such as inventory, margin, popularity, or conversion rate should influence the final order. Relevance should remain responsible for finding suitable products; business logic should refine that result rather than compensate for missing indexed content.

Combine free-text search with exact filters

Shoppers frequently enter a phrase and select filters at the same time. Keep the free-text condition separate from structured constraints so Vespa can evaluate each part correctly.

select * from sources product
where userInput(@query)
  and attribute_values contains "material:stainless steel"
  and attribute_values contains "color:silver";

For WooCommerce layered navigation, model filterable values consistently. A key-value encoding such as material:stainless steel is simple to ingest and filter, while dedicated fields such as color, size, or brand can be appropriate when the catalog has stable, high-value dimensions.

Do not rely on text matching for exact numeric or categorical filters. A text query for 10 may match unrelated descriptions, whereas a structured field can represent a specific size, capacity, or voltage value.

Handle variations deliberately

Variable WooCommerce products need an explicit indexing strategy. Indexing only the parent product can make a valid variation invisible when its distinguishing attribute exists only on the variation. Indexing every variation as a separate searchable document improves precision but requires the result layer to group or collapse variations for the storefront.

A common approach is to index variation-level values into the parent search document, while retaining variation identifiers and stock information for the purchase step. Another approach is to index each variation and use grouping in the response presentation. Choose based on whether shoppers search for variation-specific terms and whether inventory is managed independently for each variation.

Test field coverage with realistic queries

Build a test set that identifies where each expected match comes from:

  • Title terms, such as commercial blender.
  • Description terms, such as cafe kitchen.
  • Attribute terms, such as stainless steel or 1500w.
  • Mixed queries containing title and attribute language.
  • Queries combined with exact WooCommerce filters.
  • Queries for variation-only values.

For every test query, verify that the expected document is retrieved, that the matching field contributes to the rank, and that unrelated products are not promoted because of generic description text. Search logs and click or conversion events can then be used to adjust field weights and identify missing attribute normalization.

Operational considerations for agencies

Make the WooCommerce-to-Vespa mapping part of the integration contract. Document which attributes are searchable, which are filterable, how taxonomy slugs are normalized, and how deleted or unpublished products are removed from Vespa.

When a product changes, update its title, description, normalized attribute text, structured values, price, stock state, and visibility together. A stale attribute field can make search results appear inconsistent even when the product page is correct. During reindexing, use deterministic document identifiers so updates replace existing documents rather than creating duplicates.

Finally, inspect the generated Vespa queries and ranking features during development. A search implementation that appears to work for title queries may still omit descriptions, variation attributes, or exact filters. Treat field coverage, query behavior, and ranking quality as separate testable concerns.

Trending posts
You might also like