Hybrid Search: Keyword + Semantic Search

WooCommerce search has to handle two different kinds of intent. A shopper searching for waterproof trail shoes expects relevant concepts and attributes, while a shopper searching for SKU TRL-204-BLK expects an exact lexical match. Hybrid search combines keyword relevance with semantic similarity so agencies can support both behaviors in one query.

What hybrid search combines

Weaviate’s hybrid operator combines a keyword search, typically BM25, with a vector search. BM25 rewards exact terms, term frequency, and useful matches across configured properties. The vector component compares the query embedding with product embeddings, allowing related wording such as rainproof hiking footwear to match a product described as waterproof trail shoes.

The alpha value controls the balance:

• alpha=0 favors keyword search.
• alpha=1 favors vector search.
• A middle value, such as 0.5, blends both signals.

The best value depends on the catalog. SKU, model-number, and brand searches usually need stronger keyword weighting. Broad natural-language searches often benefit from a higher semantic contribution.

Designing a product collection for hybrid search

Before tuning the query, make sure the indexed product document contains useful searchable content. A typical WooCommerce product object might include:

• name: the product title.
• description: the cleaned long description.
• shortDescription: concise merchandising copy.
• sku: the exact product or variation identifier.
• brand: the manufacturer or brand name.
• attributes: searchable values such as size, color, material, and compatibility.
• categories: the product taxonomy path.

For semantic indexing, combine the fields that express product meaning into a controlled text field or configure the collection to vectorize the relevant properties. Preserve SKU and other identifiers as separate properties so the keyword component can match them precisely. Do not rely on embeddings alone for identifiers, because semantically similar product codes are not necessarily interchangeable.

Running a hybrid query with the Python client

The following example uses the Weaviate Python client and requests the score metadata for diagnostics. The exact collection and property names should match the schema used by the agency’s integration.

from weaviate.classes.query import MetadataQuery

products = client.collections.get('Product')

results = products.query.hybrid(
    query='waterproof trail shoes',
    alpha=0.55,
    query_properties=['name', 'description', 'shortDescription', 'brand', 'attributes'],
    limit=12,
    return_metadata=MetadataQuery(score=True)
)

for item in results.objects:
    print(item.properties['name'], item.metadata.score)

A value of 0.55 gives a slight preference to the vector signal while retaining strong lexical behavior. Agencies should test several values against real WooCommerce queries rather than selecting one value globally based only on a benchmark catalog.

Filtering hybrid results for WooCommerce

Search relevance and catalog constraints are separate concerns. Apply filters for publication status, stock, price, category, brand, and product visibility. For example, an agency might restrict results to in-stock products in a category while still allowing semantic matching within that filtered set.

from weaviate.classes.query import Filter, MetadataQuery

products = client.collections.get('Product')

results = products.query.hybrid(
    query='comfortable black running shoes',
    alpha=0.45,
    filters=(
        Filter.by_property('inStock').equal(True)
        & Filter.by_property('categories').contains_any(['Running Shoes'])
    ),
    limit=24,
    return_metadata=MetadataQuery(score=True)
)

Keep operational filters separate from the natural-language query. A phrase such as under $100 should not be treated as a substitute for a numeric price filter, and in stock should be enforced from indexed inventory data rather than inferred from product copy.

Controlling lexical relevance

Hybrid search can use selected properties for the keyword component. Give product names and SKUs more influence than long descriptions when exact merchandising terms matter. Property boosts are expressed using the property name followed by a caret and weight, where supported by the client and Weaviate version.

results = products.query.hybrid(
    query='ACME waterproof jacket',
    alpha=0.35,
    query_properties=['name^3', 'sku^5', 'brand^2', 'description'],
    limit=10
)

This setup prioritizes exact matches in sku and name, while the vector component can still retrieve products described with related terminology. Validate property boosting with searches for misspellings, abbreviations, model codes, brand names, and long-form shopper questions.

Inspecting and tuning result quality

When a result looks wrong, inspect the individual signals instead of tuning alpha blindly. Request score or explanation metadata where available, then compare:

• Whether the product matched the query terms lexically.
• Whether the product was semantically close but lacked important exact attributes.
• Whether a filter removed a commercially relevant result.
• Whether the indexed text contains stale, duplicated, or boilerplate WooCommerce content.

Build an evaluation set from real site-search logs. Include exact SKUs, brand-plus-category queries, feature-based queries, misspellings, synonyms, and queries with filters. Record the expected products or acceptable product groups, then compare top-five and top-ten results across different alpha values and property boosts.

Using hybrid search in a WooCommerce autocomplete flow

Autocomplete usually needs lower latency and fewer results than a search-results page. Use a small limit, return only the fields needed by the UI, and debounce requests in the storefront. Exact SKU and product-name matches should generally be favored for autocomplete, so a lower alpha is often appropriate. A full results page can use a more balanced value and expose facets or filters separately.

For a multilingual or multi-brand catalog, store language-aware text and ensure the configured vectorizer and tokenization strategy match the content. If products are updated through WooCommerce webhooks, reindex titles, descriptions, attributes, inventory flags, and taxonomy fields consistently; stale searchable text can make hybrid tuning appear ineffective.

Operational recommendations for agencies

1. Start with a representative query set from production search logs.
2. Index identifiers separately from descriptive content.
3. Use filters for commerce rules such as stock, visibility, category, and price.
4. Test several alpha values by query type rather than assuming one universal balance.
5. Inspect score metadata during development and remove unnecessary metadata from production responses.
6. Version the search configuration so changes to vectorization, boosts, and ranking can be measured during rollout.