Search & retrieval

Product catalogue, faceted search and cart signals

Gives a storefront product storage, faceted search and an abandoned-cart signal from the same database as the rest of its data.

BetaEngine edition 5f8ea3af

What it does

A product model with variants, stock and money in minor units. POST /v1/products stores a product, GET /v1/products/{id} reads it, and POST /v1/products/search combines BM25 text matching, facet filters and an optional embedding rerank into one ranked list. An opt-in background monitor publishes a realtime event for idle carts. Co-purchase recommendations exist in the engine but are not wired; see the product recommendations entry.

How it works

A product carries an external id and source, title, handle, description, a status of active, draft or archived, vendor, product type, tags, images, variants, a price and categories. Each variant has a SKU, price, optional compare-at price, options and stock as on-hand and reserved counts. Money is an integer in minor units with a currency code, which avoids floating-point rounding. Unrecognised fields are kept in an extra object, and conversion to and from the stored entity is lossless.

A search takes text, an optional embedding, brand, category, tags, a price range, an in-stock flag and a limit (default 24). With text, it takes a BM25 candidate pool from the product kind, four times the limit by default. It then applies the facets to that pool: brand matches vendor, category matches the product type or the categories list, each tag must appear in the tags list, price is a range on the amount in minor units, and the in-stock flag keeps products where some variant has on-hand stock above reserved. With an embedding, the pool is reranked by half the natural log of one plus the BM25 score, plus the cosine similarity. Without text, the search scans all products and applies the facets.

The cart monitor starts when the server is launched with KYNETRA_CART_MONITOR=true; KYNETRA_CART_IDLE_SECS sets the idle window (default 900). Every 60 seconds it looks for entities of kind cart whose last update, the updated_at_ms attribute or else the envelope timestamp, is older than the window and for which no entity of kind checkout carries the cart id in its cart_id attribute. For each one it publishes a custom realtime event on the topic cart-abandoned with the cart id, which a client receives by subscribing to the realtime stream for that topic.

Every POST to /v1/products mints a fresh id, so the route creates products. To update one, write the entity by id through the entity routes.

Where you reach it

  • HTTPPOST /v1/products, GET /v1/products/{id}, POST /v1/products/search
  • ConfigKYNETRA_CART_MONITOR, KYNETRA_CART_IDLE_SECS

Example

Faceted product search with a price ceilingbash
curl -s "$KYNETRA_URL/v1/products/search" \
  -H "Authorization: Bearer $KYNETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "trail running shoes",
    "brand": "Acme",
    "tags": ["waterproof"],
    "price_max": 15000,
    "in_stock_only": true,
    "limit": 12
  }'

# response: { "hits": [ { "score": <float>, "product": { ... } } ] }

Limits

  • Facets are applied after the BM25 pool is taken, so a selective facet can return fewer than limit results even when more products match.
  • Text matching is exact-token BM25. A misspelt query does not match; the module comment mentions fuzzy matching, but the code uses the plain search.
  • The embedding rerank is an exact cosine over the pool, not an index search, and it reorders the BM25 candidates without adding to them.
  • The product routes accept the instance API key. Project keys and end-user tokens are not accepted, and the products are not namespaced per project, so use them in a single-tenant deployment or behind your own backend.
  • The abandoned-cart event is emitted again on every scan while a cart stays idle and has no checkout. Consumers should de-duplicate by cart id.
  • The monitor reads the unprefixed kinds cart and checkout. Carts written through project-scoped keys are stored under project-prefixed kinds and are not seen.
  • No HTTP-level test of the product routes was found in the engine repository; the model, search and monitor are covered by library tests.

Evidence

  • On this siteHTTP API reference
  • Tests10 library test functions cover product round trips, faceted search, price ranges, embedding rerank and the three cart-monitor cases (stale cart, checked-out cart, fresh cart)

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.