Table of contents :

Search Filters Meet Vector Search

100-days-of-weaviate-031

Table of contents :

For WooCommerce search, semantic relevance is only half the problem. A shopper may search for “lightweight trail shoes” while also requiring a specific size, brand, price range, stock status, or product category. Vector search understands the meaning of the query; filters enforce the shopper’s business constraints. Combining both produces results that are relevant and usable.

Why vector search needs filters

A vector query can identify products that are conceptually similar to a natural-language query, even when the product title does not contain the exact words. However, similarity alone does not guarantee that a product is available, affordable, or appropriate for the selected storefront context.

For example, a WooCommerce agency might receive this request from a storefront:

{"query":"waterproof hiking boots","brand":"North Ridge","minPrice":100,"maxPrice":220,"inStock":true}

The vector component should find products related to waterproof hiking boots. The filter component should restrict the result set to North Ridge products priced between 100 and 220 with inventory available. A product that is semantically excellent but out of stock should not appear merely because its embedding is close to the query embedding.

Modeling filterable WooCommerce properties

When designing a Weaviate collection, identify the product fields that the storefront will filter frequently. Typical fields include:

  • brand and category as text or constrained categorical values.
  • price as a numeric property.
  • stockQuantity as an integer, or inStock as a boolean.
  • onSale as a boolean.
  • attributes such as color, material, or gender, represented in a way that supports the required filter expressions.
  • storeId or channel-specific visibility fields for multisite and multistore deployments.

Use consistent types and normalized values. For example, do not index some brand values as “North Ridge” and others as “north-ridge” unless the application deliberately handles that distinction. Keep prices in one currency per collection, or store an explicit currency and filter accordingly.

Combining a near-text query with filters

In Weaviate’s GraphQL API, a vector search can be combined with a where filter. The following example searches a Product collection while enforcing brand, price, and inventory constraints:

query {
  Get {
    Product(
      nearText: { concepts: ["waterproof hiking boots"] }
      where: {
        operator: And
        operands: [
          {
            path: ["brand"]
            operator: Equal
            valueText: "North Ridge"
          }
          {
            path: ["price"]
            operator: GreaterThanEqual
            valueNumber: 100
          }
          {
            path: ["price"]
            operator: LessThanEqual
            valueNumber: 220
          }
          {
            path: ["inStock"]
            operator: Equal
            valueBoolean: true
          }
        ]
      }
      limit: 24
    ) {
      productId
      name
      price
      permalink
      _additional {
        distance
      }
    }
  }
}

The nearText clause supplies the semantic search intent. The where clause limits eligible objects. The returned distance is useful for diagnostics and relevance tuning, but it should not be treated as a universal business-quality score.

Using the Python client

With the Weaviate Python client, filters can be constructed separately from the query and passed to a vector search. This keeps request-building code easier to test when filters come from WooCommerce URL parameters or a faceted-search interface.

import weaviate.classes as wvc

products = client.collections.use("Product")

filters = (
    wvc.query.Filter.by_property("brand").equal("North Ridge")
    & wvc.query.Filter.by_property("price").greater_or_equal(100)
    & wvc.query.Filter.by_property("price").less_or_equal(220)
    & wvc.query.Filter.by_property("inStock").equal(True)
)

response = products.query.near_text(
    query="waterproof hiking boots",
    filters=filters,
    limit=24,
)

for product in response.objects:
    print(product.properties["name"])

Check the client version used by the agency before copying an example into production. Weaviate client APIs evolve, while the underlying concepts remain the same: construct a filter expression, execute a vector query, and return only objects satisfying the filter.

AND and OR behavior for facets

Most storefront facets combine with AND across facet groups and OR within one group. A shopper selecting the brands North Ridge and Alpine Works usually expects products from either brand, while also requiring the selected category and price range.

brandFilter = (
    wvc.query.Filter.by_property("brand").equal("North Ridge")
    | wvc.query.Filter.by_property("brand").equal("Alpine Works")
)

filters = (
    brandFilter
    & wvc.query.Filter.by_property("category").equal("Hiking Boots")
    & wvc.query.Filter.by_property("inStock").equal(True)
)

Build these expressions from validated allowlists rather than concatenating raw user input into a GraphQL query. This prevents malformed requests and avoids exposing fields that should not be filterable.

Pre-filtering, candidate selection, and result quality

Filtered vector search is not equivalent to retrieving a large unfiltered result set and removing unsuitable products in application code. Application-side removal can leave too few results, waste query capacity, and produce unstable pagination. Supplying the filter to Weaviate allows the database to apply the constraint as part of the search operation.

Filtering is especially important for inventory and visibility. If stock changes frequently, synchronize the filterable inventory field promptly from WooCommerce. A stale inStock value can make a semantically correct search return products that cannot be purchased.

For strict requirements such as legal market restrictions, customer-specific catalogs, or permission boundaries, treat the filter as an access-control boundary. Do not rely on vector similarity, reranking, or frontend filtering to enforce those rules.

Numeric ranges and WooCommerce prices

Price filters should use numeric properties, not text. Text comparisons can produce incorrect ordering, such as treating “99” as greater than “1000” under lexical comparison. If the store supports sale prices, decide which value the search experience means by “price” and index that value explicitly.

For example, a collection may contain both regularPrice and effectivePrice. The storefront’s price facet should normally filter effectivePrice, while the display layer can show the regular price and discount information separately. For multi-currency stores, convert prices before indexing or partition searches by currency.

Pagination and empty result handling

Filters can reduce the eligible set dramatically. A query for “organic cotton t-shirt” combined with a narrow size, color, price, and stock selection may legitimately return no products. The application should distinguish an empty filtered result from a failed search and offer useful actions, such as removing the least restrictive facet or showing available facet counts.

For production pagination, use the pagination approach supported by the Weaviate client and API version in your deployment. Avoid assuming that a large offset is always efficient. If the storefront needs stable page navigation while products are changing, define a consistent sort and account for inventory and catalog updates between requests.

Testing a combined search endpoint

An agency should test the vector and filter portions independently and together. A practical test matrix includes:

  1. A semantic query with no filters returns conceptually relevant products.
  2. A restrictive brand filter returns no products from other brands.
  3. A numeric price range excludes boundary values correctly.
  4. An inventory filter excludes products whose indexed stock state is false.
  5. Multiple values in one facet use OR semantics, while separate facets use AND semantics.
  6. A query with no matching products returns a valid empty response rather than falling back to unfiltered products.
  7. Unauthorized catalog or store filters cannot be removed by editing request parameters.

Log the normalized query, filter expression, result count, and latency without logging unnecessary customer data. Comparing filtered and unfiltered result counts helps identify overly restrictive facet combinations, stale catalog fields, and poorly mapped WooCommerce attributes.

Trending posts
You might also like