postvec

Appearance

One-shot helpers ​

embed(), convert() and refresh_models() are administrative. They are revoked from PUBLIC. Application search uses search().

Use these to prove a model loads, to translate one vector or to rebuild the SQL model cache. To keep searching an existing space, see search a retired space. To change a stored column after that, use migrate().

sql
SELECT vector_dims(postvec.embed(
  'the isolated image performs inference',
  'sentence-transformers-all-minilm-l6-v2'
)::vector);

SELECT postvec.convert(
  postvec.embed('...', 'sentence-transformers-all-minilm-l6-v2'),
  'sentence-transformers-all-minilm-l6-v2',
  'baai-bge-m3'
);

SELECT postvec.refresh_models();

Expected

MiniLM returns a 384-d vector. refresh_models() returns the number of models seen; the cache write itself rewrites only the rows that changed.

Inventory and host checks: helpers (CLI).

Functions ​

FunctionUse
embed(text, model) / embed(text[], model)Confirm a model loads, or produce a vector for search_with_vector()
convert(embedding, source, target)Translate one vector through a local or direct UniVec hosted converter without starting a column migration
refresh_models()Rebuild the SQL cache after an inference-node inventory change

Grant explicitly if an application role must call them:

sql
GRANT EXECUTE ON FUNCTION postvec.embed(text, text) TO app_admin;
GRANT EXECUTE ON FUNCTION postvec.convert(real[], text, text) TO app_admin;
GRANT EXECUTE ON FUNCTION postvec.refresh_models() TO app_admin;

Input ceilings ​

embed(text[], model) takes at most 4096 items per call. Each item must fit the per-item ceiling: the smallest of postvec.max_document_bytes, postvec.max_batch_total_bytes and the 48 MiB transport limit for one message. The items together must fit postvec.max_batch_total_bytes. A call over either boundary raises before any inference runs.

embed(text, model) and the query text of search() and search_with_vector() pay the per-item ceiling too.

Managed PostgreSQL ​

On an embedded host these helpers run inference inside the PostgreSQL process. On managed PostgreSQL the schema is plpgsql and postvec-server runs the same jobs in a separate process:

  • embed(input, model) is a stub that raises, unless the call arrives through the postvec-server proxy port. Only the single-text form exists on a managed host.
  • convert() raises. POST {"source_model","target_model","embeddings"} to the server's /api/convert endpoint.
  • refresh_models() returns void and notifies the sync worker, which refreshes the postvec.models cache from the server host.

Workers refresh postvec.models on an interval. refresh_models() is the immediate path after postvec model pull (already done by the CLI on an embedded cluster) or after a remote fleet change.

Column-level work stays on enable, adopt, search a retired space and migrate.