Semantic search

How Skryx finds products by meaning, not just keyword overlap.

Keyword search works when customers know the right words. Semantic search works when they don't. Skryx ships both — and combines them with Reciprocal Rank Fusion so you don't have to choose.

# The intuition

Skryx encodes every document in your index as a dense vector — a 512-number fingerprint that captures meaning, not letters. At search time, the query gets encoded the same way, and the engine returns documents whose vectors are closest by cosine similarity.

That's why a search for "ceva pentru frig pe motor" on a Romanian auto-parts catalog surfaces antigel, termostat and răcitor ulei — none of those words appear in the query, but the engine understands the relationship.

# When to enable it

Turn it on if customers describe what they need in natural language — use-cases ("headphones for travel"), symptoms ("frana nu mai apasa"), or ambient queries ("ceva pentru frig pe motor"). Keep it off if your traffic is dominated by SKU lookups or exact brand+model queries — keyword is faster and free.

You can also leave it on and let Skryx pick: the auto search mode routes simple queries through keyword and complex ones through hybrid.

# How it works

  1. Indexing. When you enable semantic search on an index, Skryx walks every document and computes its embedding from a weighted text representation (title gets 3× weight, then brand, category, and the first 500 chars of description). A 25,000-document index typically completes in 2–3 minutes; cost is included on your plan.
  2. Query time. Your query is embedded (~150 ms first time, then cached for 24 hours). The engine returns the top 100 most-similar documents.
  3. Hybrid fusion. When search_mode is auto or hybrid, Skryx runs keyword and vector search in parallel, then merges with Reciprocal Rank Fusion (k=60). Documents that rank well in both signals come out on top.

# Modes

Mode What runs When to use
keyword BM25 only — fastest, free Default for tiny indexes; SKU-heavy traffic.
semantic Vector similarity only Conversational search; when keyword returns 0.
hybrid Keyword + vector, fused with RRF The right default for most catalogs.
auto Heuristic — SKU/1-2 words → keyword; otherwise hybrid Set-and-forget.

The search_mode parameter on POST /v1/indexes/{name}/query overrides the index default per request.

# What's returned

When semantic or hybrid runs, every hit carries a match_type:

{
  "document": { "id": "418", "title": "Antigel concentrat verde 1L" },
  "match_type": "semantic",          // 'keyword' | 'semantic' | 'hybrid'
  "vector_distance": 0.247           // cosine distance (semantic / hybrid only)
}

The top-level response also includes search_mode (the mode actually used, which may differ from what you asked for — see auto and the cost guards below) and embed_time_ms (how long the query embedding took, 0 on cache hit).

# Cost

  • Indexing: one-time, charged in tokens. A 25k-product Romanian auto-parts catalog costs around $0.07 to embed end-to-end.
  • Queries: each unique query produces one query embedding. Cache hit rate in the wild is typically 60–80% after a few days of real traffic.
  • Caps: Growth = 100,000 semantic queries/month; Business = 1M; Enterprise = unlimited. When the cap is hit, Skryx silently falls back to keyword — your search never breaks.

# Enabling it

From the dashboard: open Indexes → {your index} → Search Settings, scroll to the Semantic Search card, click Enable. Indexing runs in the background; the page shows live progress.

From the API:

curl -X POST https://api.skryx.io/v1/indexes/products/semantic-search/enable \
  -H "Authorization: Bearer $SKRYX_API_KEY"

See the semantic-search lifecycle endpoints for the full reference.

esc