AI & agents

Embedding on write

Keeps vectors current without every client having to call an embedding model before each write.

BetaEngine edition 5f8ea3af

What it does

A collection can list text fields in embed_source. When a record is inserted through the REST plane without an embedding, the server joins those fields, asks an Ollama-compatible embedding endpoint for a vector and stores it as the record embedding, so the vector and hybrid routes work with no client-side embedding step. If the endpoint fails, the record is stored without a vector.

How it works

embed_source is part of the collection definition, set with POST /v1/collections by an admin or service credential. On POST /rest/v1/{table}, for each inserted row, the server checks three things: the collection declares embed_source, the row carries no embedding of its own, and the joined text of the named string fields is not blank. A client-supplied embedding always wins.

When all three hold, the server posts the text to the embeddings endpoint of an Ollama-compatible server (KYNETRA_EMBED_URL, default http://127.0.0.1:11434, at /api/embeddings, with the model from KYNETRA_EMBED_MODEL, default nomic-embed-text) and writes the returned vector into the row embedding. This happens before row-level security checks and validation, so a computed vector follows the same path as a supplied one.

The step is deliberately forgiving. If the endpoint is unreachable, returns an error or returns an empty vector, the server logs a warning and stores the record without a vector rather than failing the write.

Where you reach it

  • HTTPPOST /v1/collections with embed_source; POST /rest/v1/{table}
  • ConfigKYNETRA_EMBED_URL, KYNETRA_EMBED_MODEL

Example

POST /v1/collections: embed title and body on insertjson
{
  "name": "articles",
  "fields": [
    { "name": "title", "type": "text" },
    { "name": "body", "type": "long_text" }
  ],
  "embed_source": ["title", "body"],
  "created_at": 0,
  "updated_at": 0
}

Limits

  • An Ollama-compatible embeddings endpoint is the one supported kind. The vector width is whatever the model returns; it is not checked against anything stored, and the exact scan skips vectors whose width differs from the query.
  • Embedding happens on insert and at no other time. Updates through PATCH and writes through the collection record routes do not re-embed.
  • Failure is silent to the caller: the write succeeds without a vector and the sole trace is a server log line. Monitor for unembedded records if search depends on them.
  • Each inserted row makes its own sequential call to the endpoint, so a large batch insert waits on that endpoint.
  • The text of every inserted row is sent to the configured endpoint. Choose a local endpoint if the data must stay inside your network.
  • String fields are used; other types named in embed_source are ignored.
  • The tests in the engine repository cover the collection setting; no automated test of the insert path was found.

Evidence

  • On this siteHTTP API reference
  • TestsA schema test checks that embed_source defaults empty, accepts older stored collections and round-trips when set

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.