WooCommerce search results often give too much weight to long product descriptions, attributes, and imported metadata. That can make a category name or product name match less prominently than an incidental phrase in the body of a description. Weaviate lets you control this behavior by boosting the fields that matter most to shoppers.
Why product names and categories need more weight
A customer searching for linen shirt usually expects products with those words in the product name or assigned category to rank ahead of products that only mention linen in their description. A product name is a strong signal of relevance, while a description match is often supporting evidence.
For a WooCommerce catalog, useful searchable properties commonly include:
- name: the WooCommerce product name.
- categories: one or more category names, such as Men, Shirts, or Organic Clothing.
- shortDescription: concise merchandising copy.
- description: the full product description.
- sku: an exact or near-exact identifier.
- attributes: searchable values such as color, material, or size.
Modeling the WooCommerce data
A practical product object can store category names as an array of text values. Keeping category names on the product makes them available to keyword and hybrid search without requiring an additional lookup during every query.
{
"name": "Organic Linen Shirt",
"categories": ["Men", "Shirts", "Organic Clothing"],
"shortDescription": "A lightweight linen shirt for warm weather.",
"description": "Made from breathable organic linen with a relaxed fit.",
"sku": "LINEN-001"
}
When synchronizing products from WooCommerce, normalize category values consistently. Remove HTML from descriptions, preserve the original product name, and decide whether parent categories should be included. Including both Shirts and Men > Shirts, for example, can improve matching but may also increase duplicate signals if the same terms are repeated in several fields.
Boosting fields with BM25 keyword search
Weaviate supports property-level weighting for BM25 searches by using boost notation in the query properties. A value such as name^4 gives the product name more influence than an unboosted property, while categories^3 gives category matches substantial weight.
The following example uses the Weaviate Python client. Property names and collection names should match the schema used by the agency’s implementation.
from weaviate.classes.query import MetadataQuery
products = client.collections.get("Product")
response = products.query.bm25(
query="linen shirt",
query_properties=[
"name^4",
"categories^3",
"shortDescription^2",
"attributes^2",
"description"
],
return_metadata=MetadataQuery(score=True),
limit=20
)
for product in response.objects:
print(product.properties["name"], product.metadata.score)
The exact multipliers are not universal. A sensible starting point is to boost the product name most strongly, categories next, and longer descriptive fields less strongly. Measure the results with real WooCommerce queries rather than assuming that a larger multiplier always produces a better ranking.
Combining keyword boosts with semantic search
Keyword boosting is especially useful for brand names, category labels, SKUs, and precise product terminology. Semantic search is useful when the shopper’s wording differs from the catalog wording, such as searching for breathable summer top when the product is named Organic Linen Shirt.
A hybrid query combines both signals. In the Python client, the alpha value controls the balance between vector and keyword search. A lower value gives more influence to the keyword component; a higher value gives more influence to the vector component.
response = products.query.hybrid(
query="linen shirt",
query_properties=[
"name^4",
"categories^3",
"shortDescription^2",
"attributes^2",
"description"
],
alpha=0.35,
return_metadata=MetadataQuery(score=True),
limit=20
)
For catalogs where exact category and product-name matches are critical, start with a keyword-heavy balance such as alpha=0.25 to 0.45. Increase the value when shoppers frequently use natural-language descriptions that do not occur verbatim in the catalog.
Category-aware filtering and boosting
Boosting is not the same as filtering. If a shopper selects the WooCommerce category Shirts, the category should usually be applied as a filter so unrelated products cannot outrank matching products. If the shopper merely types shirts into the search box, category boosting can help relevant products rise without excluding other useful results.
Keep these behaviors separate in the search interface:
- Free-text search: use boosted product names and categories to influence ranking.
- Selected category facet: use a category filter to restrict the result set.
- Category landing page: use the category as a filter and apply normal merchandising rules within that set.
If categories are stored as text, a filter can be built against the category property. If the catalog requires reliable category identity, hierarchy, or localized labels, model categories as referenced objects or store stable category IDs alongside display names. Stable IDs prevent a renamed category from breaking filters and synchronization logic.
Handling exact product names and SKUs
Product-name boosting alone may not be enough for identifiers. A customer searching for an exact SKU should not receive a result merely because the SKU tokens appear in a long description. Consider a separate exact-match path for normalized SKUs and product slugs, followed by the broader BM25 or hybrid query when no exact match is found.
normalized_query = user_query.strip().upper()
# Use an exact lookup or an equality filter for normalized SKU values
# before running the broader relevance query.
exact_matches = products.query.fetch_objects(
filters=Filter.by_property("sku").equal(normalized_query),
limit=10
)
The exact lookup should be treated as a deliberate business rule, not as a replacement for relevance ranking. Validate and normalize SKU values during ingestion so that differences in capitalization, whitespace, and punctuation do not create avoidable misses.
Preventing category overmatching
Category boosting can become too aggressive when every product has many broad categories. A product assigned to Clothing, Men, Shirts, and Summer may receive several signals for a query that matches only one general term. Review the taxonomy before increasing weights.
- Use specific merchandising categories where possible.
- Avoid copying the complete category path into multiple text properties.
- Keep facets and search text separate when a category is intended only for navigation.
- Test broad terms such as
gift,sale, andmenseparately from precise product queries.
Evaluating ranking changes
Agencies should evaluate boosted searches with a query set drawn from real WooCommerce analytics, site-search logs, and support tickets. Include exact product names, category terms, synonyms, misspellings, attribute combinations, and queries with no expected results.
For each query, record whether the expected products appear in the top five or top ten results. Also inspect undesirable results: a product that mentions a term in its description should not consistently outrank a product whose name matches the query exactly.
Compare a baseline configuration with one change at a time:
- Run the query set without property boosts.
- Boost
nameand measure product-name queries. - Add the
categoriesboost and measure category queries. - Add hybrid search and test natural-language queries.
- Adjust
alphaand multipliers only after reviewing failures.
Operational guidance for WooCommerce agencies
Keep boost values in configuration rather than embedding them throughout application code. This allows a merchandising team to test ranking changes without changing the data model or synchronization process.
SEARCH_PROPERTIES = [
"name^4",
"categories^3",
"shortDescription^2",
"attributes^2",
"description"
]
HYBRID_ALPHA = 0.35
response = products.query.hybrid(
query=search_text,
query_properties=SEARCH_PROPERTIES,
alpha=HYBRID_ALPHA,
limit=20
)
When a product or category changes in WooCommerce, update the corresponding Weaviate object promptly. Reindexing is important after changing category names, removing assignments, or cleaning descriptions; otherwise, the ranking configuration may be correct while the indexed text remains stale. Log the query, applied filters, boost configuration, and result identifiers so ranking regressions can be investigated without exposing unnecessary customer data.
Recommended starting configuration
For a typical WooCommerce catalog, begin with name^4, categories^3, concise merchandising fields at ^2, and the full description unboosted. Use hybrid search when semantic matching adds value, but keep enough keyword influence to preserve exact product-name and category behavior. Then tune the values against real queries and review both relevance improvements and new failure cases.