Search & retrieval

Vector similarity search

Finds the records whose embeddings sit closest to a query embedding, so an application can search by meaning without running a separate vector store.

BetaEngine edition 5f8ea3af

What it does

POST /v1/vector takes a query embedding and returns the entities whose stored embeddings have the highest cosine similarity, optionally restricted by kind or a metadata filter. On the stock server this is an exact scan over every stored embedding: recall is perfect and cost grows with the number of vectors. On the Postgres backend with pgvector enabled, the same route is served by a Postgres-side index.

How it works

Embeddings are stored on the entity itself. A client attaches one when it writes an entity (the embedding field of POST /v1/entities or POST /v1/products, or an MCP put), or a collection can name text fields that the server embeds on insert; see the embedding-on-write capability. The plain entity write path does not generate embeddings.

A query supplies a vector, top_k (default 24) and optionally kind and filter. The exact path scores every entity whose embedding has the same dimension as the query, using cosine similarity, in parallel across CPU cores, and returns the top hits as id, kind and score. Entities whose embedding has a different dimension are skipped rather than reported as errors, so keep one model and one width per kind.

Each hit is re-read and checked against the same read-visibility rule that entity reads use. A project service key is confined to its own namespace: kind and filter are composed with a namespace guard before any scoring happens, so a filter written by one tenant cannot match rows that belong to another.

With the Postgres storage backend (KYNETRA_STORAGE_BACKEND=postgres) and KYNETRA_PG_VECTOR=true, the engine maintains a derived vectors table in the same transaction as each log append and hands the nearest-neighbour search to Postgres, which uses an HNSW index when KYNETRA_PG_VECTOR_DIM fixes the dimension. If the vector extension is missing, the engine logs a warning and falls back to the in-memory scan. With a filter, this path fetches four times k and filters in memory, so a selective filter can return fewer than k hits.

The engine also contains approximate indexes (an in-memory HNSW graph and a disk-resident SPANN index, with several quantisation modes). The server does not build or enable them on any setting, so they are described as roadmap entries. The published recall and latency artifacts were measured on those library indexes and say nothing about this exact scan.

Where you reach it

  • HTTPPOST /v1/vector { vector, top_k, kind, filter }
  • CLIkynetra search '[0.12, 0.31, ...]' --top-k 10 --kind product (remote mode posts to /v1/vector)
  • SDKSearchClient.vector in the TypeScript, Python, Go and Rust client sources
  • MCPkynetra_vector_search (HTTP /mcp and the stdio kynetra-mcp server)
  • ConfigKYNETRA_STORAGE_BACKEND=postgres, KYNETRA_PG_VECTOR=true, KYNETRA_PG_VECTOR_DIM

Example

Nearest products to a query embeddingbash
curl -s "$KYNETRA_URL/v1/vector" \
  -H "Authorization: Bearer $KYNETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vector": [0.12, 0.31, -0.08, 0.44], "top_k": 5, "kind": "product" }'

# response shape
# { "hits": [ { "id": "...", "kind": "product", "score": <cosine similarity> } ] }

Limits

  • The exact scan costs time proportional to the number of embeddings with the query dimension. No latency figure has been published for this path on the server; measure your own corpus before relying on it at scale.
  • No approximate index is built by the server. The HNSW and SPANN indexes are engine-library features today.
  • Cosine similarity is the sole metric. There is no per-index schema, so nothing stops two models of the same width from sharing a kind.
  • The TypeScript client comments describe this route as approximate nearest-neighbour search. On the stock server it is exact.
  • The Postgres vector path needs a Postgres instance with the vector extension, and its one test is gated on an environment variable that points at such an instance, so it is skipped when the variable is unset.
  • The route accepts service credentials: the instance key or a project service key. Anonymous project keys and end-user tokens are refused.

Evidence

  • On this siteHTTP API reference
  • TestsEngine tests run the exact scan without an index (one write, three query shapes; pre-filtered search); the mounted route is exercised by HTTP tests for atomic visibility, tenant scoping and recovery refusal; one Postgres test covers pgvector when a database URL is supplied

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.