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
dimensionsfour-byte floats counts as absent, andgetdeletes it. getrecords a row's use at most once a day. WithmaxIdleMs, a row unused that long is absent and is not refreshed;removeUnusedSincedeletes 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
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
The tenant.
embedding
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
The tenant.
embedding
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.