Skip to main content

Class: SqlEmbeddingStore

Defined in: packages/agentos/src/cognition/rag/embeddings/SqlEmbeddingStore.ts:187

Embedding vectors by the hash of their exact input, kept per tenant, model and vector size, on any database @framers/sql-storage-adapter opens. The store keeps no text: a host computes each input's hash with embeddingInputHash, asks for the hashes it is about to embed, embeds only the ones not answered, and stores those.

  • A call always names its tenant, and a row is answered only to its own tenant, model and size.
  • A row whose vector is not dimensions four-byte floats counts as absent, and get deletes it.
  • get records a row's use at most once a day. With maxIdleMs, a row unused that long is absent and is not refreshed; removeUnusedSince deletes such rows, on a timer the host runs.

Example​

const store = new SqlEmbeddingStore({ adapter, prefix: 'shared_sentence', manageSchema: false, maxIdleMs: 31 * 86_400_000 });
const model = { model: 'text-embedding-3-small', dimensions: 1536 };
const hashes = inputs.map((input) => embeddingInputHash(model, input));
const known = await store.get({ tenant }, model, hashes);
// One input a hash, so a sentence the batch holds twice is embedded once.
const missing = [...new Map(inputs.map((input, i) => [hashes[i], input])).entries()].filter(([hash]) => !known.has(hash));
const made = await embed(missing.map(([, input]) => input));
await store.put({ tenant }, model, made.map((vector, i) => ({ hash: missing[i][0], vector })));

Constructors​

Constructor​

new SqlEmbeddingStore(options): SqlEmbeddingStore

Defined in: packages/agentos/src/cognition/rag/embeddings/SqlEmbeddingStore.ts:202

Parameters​

options​

SqlEmbeddingStoreOptions

The adapter, the table prefix, whether to create the table, the idle limit and the clock.

Returns​

SqlEmbeddingStore

Throws​

invalid_embedding_table_prefix for a malformed prefix, and invalid_embedding_max_idle for a maxIdleMs that is not an integer of more than a day.

Methods​

get()​

get(scope, embedding, hashes): Promise<Map<string, number[]>>

Defined in: packages/agentos/src/cognition/rag/embeddings/SqlEmbeddingStore.ts:229

The stored vectors of these input hashes, for one tenant, model and size. A hash with no row, a row of another tenant, model or size, a row unused for longer than maxIdleMs, and a row whose vector is not dimensions numbers are all left out; the last kind is deleted while it still holds the vector read, so a vector another call stored under the key since stays. A row answered whose last recorded use is more than a day old has its use recorded now.

Parameters​

scope​

EmbeddingStoreScope

The tenant.

embedding​

EmbeddingStoreModel

The model and vector size.

hashes​

readonly string[]

Input hashes, as embeddingInputHash gives them. Repeats are read once.

Returns​

Promise<Map<string, number[]>>

Each answered hash with its vector, at four-byte precision.

Throws​

invalid_embedding_scope, invalid_embedding_model or invalid_embedding_hash for a malformed argument, before anything is read; the adapter's error when a statement fails.


put()​

put(scope, embedding, rows): Promise<number>

Defined in: packages/agentos/src/cognition/rag/embeddings/SqlEmbeddingStore.ts:290

Stores vectors for one tenant, model and size. A hash already stored there gets the new vector and token count, and its use is recorded now; its creation time stays. Every row is checked before anything is written, and the rows are written in one transaction where the adapter has transactions. A repeated hash is written once, with its last vector.

Parameters​

scope​

EmbeddingStoreScope

The tenant.

embedding​

EmbeddingStoreModel

The model and vector size.

rows​

readonly EmbeddingStoreRow[]

The input hashes with their vectors and token counts.

Returns​

Promise<number>

How many rows were written.

Throws​

invalid_embedding_scope, invalid_embedding_model, invalid_embedding_hash, invalid_embedding_vector (not dimensions finite numbers) or invalid_embedding_tokens (not an integer of 0 or more), before anything is written; the adapter's error when a statement fails.


remove()​

remove(scope): Promise<number>

Defined in: packages/agentos/src/cognition/rag/embeddings/SqlEmbeddingStore.ts:330

Deletes every row of one tenant, whatever its model or size.

Parameters​

scope​

EmbeddingStoreScope

The tenant.

Returns​

Promise<number>

How many rows were deleted.

Throws​

invalid_embedding_scope for a malformed scope; the adapter's error when the statement fails.


removeUnusedSince()​

removeUnusedSince(before, scope): Promise<number>

Defined in: packages/agentos/src/cognition/rag/embeddings/SqlEmbeddingStore.ts:347

Deletes one tenant's rows whose last recorded use is before before. A host with maxIdleMs runs it on a timer of its own with now - maxIdleMs, so rows get no longer answers go whether or not anything is written again.

Parameters​

before​

A time, as epoch milliseconds or a Date.

number | Date

scope​

EmbeddingStoreScope

The tenant.

Returns​

Promise<number>

How many rows were deleted.

Throws​

invalid_embedding_time for a time that is not an integer of 0 or more, and invalid_embedding_scope for a malformed scope; the adapter's error when the statement fails.