Querying WooCommerce Products with YQL

When WooCommerce products are imported into Vespa, YQL becomes the query layer used to search, filter, sort, and group the catalog. For an agency, this provides a consistent way to power product search, category landing pages, faceted navigation, and custom merchandising experiences without querying WordPress for every request.

The exact field names depend on the Vespa schema used by your integration. The examples below assume a document type named product with fields such as product_id, title, description, categories, price, stock_status, on_sale, and published.

A basic WooCommerce product query

A YQL request selects documents from a document source and applies a Boolean condition:

select * from product where true

Using true is useful when testing the schema or retrieving a complete result set. In a production application, add a limit and pagination parameters to prevent unnecessarily large responses:

select * from product where true

A typical HTTP request might look like this:

GET https://search.example.com/search/?yql=select%20*%20from%20product%20where%20true&hits=20&offset=0

The hits parameter controls the number of results returned, while offset supports simple offset pagination. For high-volume catalogs, cursor-style or continuation-based pagination may be preferable to deep offsets.

Searching product text

For customer-entered search terms, use Vespa’s query input feature rather than constructing a separate YQL expression for every phrase:

select * from product where userInput(@user-query)

Pass the search text as a query parameter:

GET https://search.example.com/search/?yql=select%20*%20from%20product%20where%20userInput(%40user-query)&user-query=waterproof%20hiking%20boots&hits=24

userInput(@user-query) converts the supplied text into a query expression using the configured Vespa search definitions. Those definitions should map the relevant WooCommerce fields, such as product name, SKU, short description, long description, brand, and attributes, to searchable indexes.

For a fixed field-level condition, a query can use a field expression directly:

select * from product where title contains "boots"

Use the user-input form for public search boxes so that query parsing, tokenization, and field weighting remain controlled by the Vespa configuration rather than by string concatenation in application code.

Filtering WooCommerce products

WooCommerce filters are normally represented as additional conditions joined with and. For example, a product listing can restrict results to published, in-stock products under a maximum price:

select * from product where published = true and stock_status = "instock" and price <= 100

Category and taxonomy fields require a schema that matches the way the importer stores values. If category_ids is an array or weighted set, an equality condition can test membership:

select * from product where category_ids contains " footwear "

The value and operator must match the field type and the indexed representation. For example, an integration that stores numeric category IDs may use:

select * from product where category_ids contains "123"

Combine a text query with catalog filters by placing both expressions in the same where clause:

select * from product where userInput(@user-query) and published = true and on_sale = true

For a WooCommerce agency, this approach keeps business rules such as visibility, stock, sale status, and customer-specific availability close to the search request while leaving the source product data in WooCommerce.

Range filters and price handling

Price should generally be indexed as a numeric Vespa field if the application needs range filtering or numeric sorting. A price-range request can then use ordinary comparisons:

select * from product where price >= 50 and price <= 150

Do not index formatted currency strings such as $149.99 when the value will be used for numeric operations. Store a normalized numeric amount, and keep currency metadata in a separate field if the catalog supports multiple currencies.

When a store has variable products, decide whether the indexed document represents the parent product, each variation, or both. A parent-only price field can produce incorrect results when variations have different prices. Many implementations store minimum and maximum variation prices and query those fields according to the storefront requirement.

Sorting and ranking results

Text relevance and business sorting are separate concerns. A search request can use a ranking profile for relevance:

select * from product where userInput(@user-query)&rankprofile=product_search

For an explicit numeric sort, use the ranking query parameter:

select * from product where published = true&ranking=price_ascending

The named rank profile must be defined in the Vespa application package. A rank profile can combine textual relevance with signals imported from WooCommerce, such as sales volume, product rating, inventory level, or a manually assigned merchandising score.

For example, a profile might use text relevance as the primary signal and then incorporate a normalized popularity value. Keep ranking features explicit and test them against representative search queries; otherwise, a high-sales product can overwhelm a more relevant result.

Facets and grouped product results

Faceted navigation can be implemented with YQL grouping. The following example groups matching products by a category field and returns the number of products in each category:

select * from product where userInput(@user-query) | all(group(category) each(output(count())))

The grouping syntax and output expressions should be tested against the field type and Vespa version used by the application. For fields containing category names, brands, or attribute values, grouping can provide the aggregation data needed to render storefront filters without a separate aggregation service.

Operational recommendations for agencies

• Define a stable document schema before building storefront queries. Field names, types, indexing modes, and array representations should not be inferred dynamically from WooCommerce metadata.
• Keep product visibility rules explicit. Exclude draft, private, trashed, and catalog-hidden products during indexing or query time according to the client’s requirements.
• Encode query parameters correctly when generating REST requests. Values such as @user-query, spaces, quotation marks, and ampersands must be URL encoded.
• Use schema-aware filters for taxonomies and attributes. A WooCommerce attribute label is not interchangeable with its term ID or internal taxonomy slug.
• Test queries with products that have variations, missing prices, multiple categories, backorders, translated content, and scheduled publication dates.
• Log the generated YQL, query parameters, response time, hit count, and ranking profile in a non-sensitive diagnostic mode so search issues can be reproduced.

In practice, a WooCommerce search endpoint can accept the customer’s text and filters, validate them against an allowed set of fields, build a parameterized YQL request, and return Vespa’s product documents to the storefront. This separates catalog retrieval from WordPress page rendering while preserving WooCommerce as the system of record.