Search & retrieval

Filtered vector search

Restricts a nearest-neighbour search to one tenant, kind or attribute value so that top_k means the top results among the records you are allowed to see.

BetaEngine edition 5f8ea3af

What it does

The kind and filter fields of POST /v1/vector and POST /v1/hybrid apply a metadata pre-filter before ranking, so results come from the filtered set and top_k is honoured against it. On the stock server the filter is applied during an exact scan. The engine also contains a selectivity-aware router for filtered queries over an approximate index, which engages when such an index exists and not otherwise.

How it works

The filter is a typed tree: all, kind, eq, ne, gt, lt, gte, lte, in, contains, like, ilike, exists, and, or and not, each addressing an attribute by path. The server turns kind and filter into one filter and, for a project service key, wraps it in a namespace guard so rows from other projects can never match.

Without an index, the exact scan evaluates the filter on each entity first and scores just the survivors. Recall is perfect by construction and the cost depends on the corpus size rather than on the filter.

When an approximate index has been built (library use today), the engine resolves the filter to a candidate id set, using the equality index where the filter shape allows it. If the set holds 4,096 entities or fewer, it scores them exactly and never consults the graph. Above that size it searches the graph or the disk index with an over-fetch scaled by 1 divided by the selectivity, capped at 50,000 candidates, then re-checks every returned hit against the filter before truncating to k. The re-check matters because the index resolution can over-approximate for a long conjunction.

The reason the router exists is recorded in a published baseline: before the optimisation, filtered search on the HNSW graph degraded sharply as selectivity dropped. Measured, local scope, one host (Cortex-X925, 121 GB RAM): unfiltered reference p99 of 0.382 ms at recall@10 of 1.0, degrading to a p99 of 8.075 ms and recall@10 of 0.004 once a 0.1% selectivity filter was applied. The artifact declares itself a baseline with no gate and notes that the host was under background load. A before-and-after artifact for the optimised router is published next to it.

Where you reach it

  • HTTPPOST /v1/vector { vector, top_k, kind, filter }
  • HTTPPOST /v1/hybrid { q, vector, top_k, kind, filter }
  • SDKVectorOpts.filter and HybridOpts.filter in the TypeScript client source

Example

POST /v1/vector with a metadata pre-filterjson
{
  "vector": [0.12, 0.31, -0.08, 0.44],
  "top_k": 5,
  "kind": "product",
  "filter": {
    "op": "and",
    "items": [
      { "op": "eq", "path": "brand", "value": "Acme" },
      { "op": "lte", "path": "price.amount_minor", "value": 5000 }
    ]
  }
}

Limits

  • On the stock server the filter runs inside an exact scan, so cost grows with the corpus even for a very selective filter. The selectivity router and its over-fetch rules apply to an approximate index built through the engine library, not to the exact scan.
  • On the Postgres vector path a filter is applied after fetching four times k, so a selective filter can return fewer than k hits.
  • The published filtered-search artifacts measure the library index on one Linux host that was under background load; absolute latencies there are higher than a quiet capture, and just the back-to-back before-and-after comparison is meaningful.
  • The hybrid route does not report how many matches top_k cut off. It signals a clamp solely when the requested top_k was reduced to 200.

Evidence

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

Every figure on this site is local-scope: one host, one operator, no third-party reproduction. Artifacts are linked next to each number, and gates that were missed are published beside the gates that were met.

KynetraDB is in private preview

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