Vector Search (totalum-sdk/vectors)

import … from 'totalum-sdk/vectors' — or the same namespace on totalum from 'totalum-sdk'. Install, configuration and errors: Totalum SDK.

Semantic search over your own content: store texts or images as vectors with metadata (upsert), then find the closest ones to a question, a text or an image (query). Totalum embeds the text and images for you and keeps each project environment's vectors private. Use it for "search by meaning", recommendations and retrieval for an AI answer. Server-side code only. Writes and queries are billed in credits; count() is free.

await totalum.vectors.upsert([{ id: 'faq-1', text: 'Refunds are possible for 30 days.', metadata: { source: 'faq' } }]);
const { matches } = await totalum.vectors.query({ text: 'Can I get my money back?', topK: 3 });

#totalumVectors

totalumVectors(options?: TotalumClientOptions): TotalumVectors

Creates the vectors namespace (the same object as totalum.vectors; scope vectors; server-side code only: it needs the project key). Every project environment has its own private vector store: ids, namespaces and indexes are Totalum's, never yours to name, and x-totalum-env (the env option) keeps dev and live apart. Vectors are 1,024 numbers; text is embedded with the embed model and image (a project file key, a files URL, an https URL or a data URL) with the embed-image model, whose space also embeds text: search images by words with space: 'image'. Filter on the metadata keys source, type, tag, group (strings) and page (number).

Parameters

Returns TotalumVectors — The vectors namespace: the methods below.

Example

import { totalumVectors } from 'totalum-sdk/vectors';

const vectors = totalumVectors();
const { count } = await vectors.count();

The namespace's type is exported as TotalumVectors (import type { TotalumVectors } from 'totalum-sdk/vectors').

#vectors.upsert

vectors.upsert(vectors: VectorUpsertItem[]): Promise<{ upserted, count, usage }>

Stores up to 100 items (at most 8 of them images) for semantic search: give each an id of yours (the row id), its content as text, image or ready-made values, and metadata to filter on. Writing an existing id replaces it. The answer (and count()) means stored; query and get see the write later — often seconds, sometimes 10+ minutes (the index applies writes asynchronously). Never wait or poll for a write to become searchable.

Parameters

Returns Promise<{ upserted, count, usage }> — How many were written, how many the environment now holds, and what it cost.

Errors — besides the errors every call can throw:

Example

await totalum.vectors.upsert([
  { id: 'faq-12', text: 'Refunds are possible for 30 days after purchase.', metadata: { source: 'faq', tag: 'billing' } },
  { id: 'product-88', image: product.photo.key, metadata: { type: 'product' } },
]);

Result:

{ "upserted": 2, "count": 2, "usage": { "credits": 0.0021 } }

#vectors.query

vectors.query(input: VectorsQueryInput): Promise<{ matches, usage }>

Finds the stored items closest in meaning to a text, an image or a vector — "search by meaning". Results are best first with a similarity score; filter them on metadata. Pass exactly one of text, image or values.

Parameters

Returns Promise<{ matches, usage }> — The closest items (best first) and what the query cost.

Errors — besides the errors every call can throw:

Examples

const { matches } = await totalum.vectors.query({
  text: 'Can I get my money back?',
  topK: 3,
  filter: { source: 'faq' },
});

Result:

{
  "matches": [
    { "id": "faq-12", "score": 0.83, "space": "text", "metadata": { "source": "faq", "tag": "billing" } },
    { "id": "faq-07", "score": 0.61, "space": "text", "metadata": { "source": "faq", "tag": "orders" } }
  ],
  "usage": { "credits": 0.0006 }
}

// images that look like a description (image search by words)
const { matches } = await totalum.vectors.query({ text: 'red running shoes', space: 'image', topK: 8 });

#vectors.get

vectors.get(ids: string[]): Promise<VectorRecord[]>

Reads stored items back by id, with their numbers and metadata. Unknown ids — and ids written in the last seconds or minutes — are left out of the answer. Free.

Parameters

Returns Promise<VectorRecord[]> — The items found (possibly fewer than asked).

Each item:

Errors — besides the errors every call can throw:

Example

const [doc] = await totalum.vectors.get(['faq-12']);

Result:

[
  { "id": "faq-12", "space": "text", "values": [0.0138, -0.0121, 0.0125, …], "metadata": { "source": "faq", "tag": "billing" } }
]

#vectors.delete

vectors.delete(ids: string[]): Promise<{ count, deleted, usage }>

Deletes items by id — when the row they describe is deleted. Ids that do not exist are ignored.

Parameters

Returns Promise<{ count, deleted, usage }> — How many existed and were deleted, how many the environment still holds, and what it cost.

Errors — besides the errors every call can throw:

Example

const out = await totalum.vectors.delete(['faq-12', 'faq-13']);

Result:

{ "deleted": 1, "count": 41, "usage": { "credits": 0 } }

#vectors.count

vectors.count(): Promise<{ count, text, image }>

How many items this environment stores, in total and per space. Free.

Returns Promise<{ count, text, image }> — The totals.

Errors — besides the errors every call can throw:

Example

const counts = await totalum.vectors.count();

Result:

{ "count": 42, "text": 40, "image": 2 }

#VectorFilter

A metadata filter for vectors.query(): an object from a metadata key (source, type, tag, group — strings — or page — a number) to a value it must equal, or to an operator object: $eq, $ne (equal, not equal), $in, $nin (one of, none of a list), $lt, $lte, $gt, $gte (ranges). Example: { source: "faq", page: { $gte: 3 } }. Strings are compared on their first 64 bytes.

#VectorMatch

One result of vectors.query().

#VectorMetadata

The metadata stored with an item: an object from string keys (not starting with _) to a string, a number, a boolean or a list of strings; at most 9 KB as JSON.

type VectorMetadata = Record<string, string | number | boolean | string[]>

#VectorRecord

A stored item, from vectors.get().

#VectorSpace

Which embedding space an item lives in.

#VectorsQueryInput

What vectors.query() searches for: exactly one of text, image or values.

#VectorUpsertItem

One item to store with vectors.upsert(): an id, exactly one content (text, image or values) and optional metadata.