Skip to content

Vector search

Vector search finds entries by meaning, not by exact words: a search for “forgot my password” finds the entry “How to reset your password”. Each entry is turned into a vector, a list of numbers that places it near entries that mean similar things, and a query returns the nearest ones.

Entries live in collections. Make one collection per kind of thing you search: help articles in one, products in another. Each entry carries an id, the text (or your own vector), and a small data object you can filter on and read back. client.vectors and muhkoo vectors arrived in @muhkoo/connect and @muhkoo/cli 0.15.0-alpha.12.

There are two modes:

  • Text mode. You send text; Muhkoo makes the vectors with the model you chose. This is what most apps want.
  • Vectors mode. You make the vectors yourself and send them, each exactly the collection’s dimensions long (1 to 1,536).

Only the app owner manages collections (create, drop, notice Spaces), as with database tables. Create one in the portal, the CLI or the SDK.

Open your app in the portal, go to Collections, and create a collection: name, mode, model (or dimensions), metric, filterable fields and access.

A definition has these parts:

PartValues
nameLowercase: ^[a-z][a-z0-9_]{0,62}$
modetext or vectors
model (text mode)bge-small-en-v1.5 (384 dimensions), bge-base-en-v1.5 (768, the default), bge-large-en-v1.5 (1024), bge-m3 (1024, multilingual), qwen3-embedding-0.6b (1024, multilingual)
dimensions (vectors mode)1 to 1,536
metriccosine (default), euclidean or dot-product
fieldsUp to 10 filterable fields, each string, number or boolean
accessapp (default; the browser’s publishable key works) or backend (secret keys, access tokens, functions and agents only)

Creating takes from seconds to a few minutes; the collection’s status is creating until it is ready. A definition never changes. Mode, model, fields and access are fixed: to change one, drop the collection (which deletes its entries) and create it again.

Your app’s test and live environments share the definition but not the entries. A call’s environment comes from its key (mk_test_… or mk_live_…), and each environment has its own entries, status, entry count and notice Spaces.

const docs = client.vectors.collection("docs");
const { mutationId, count } = await docs.upsert([
{
id: "faq-reset",
text: "How to reset your password: open Settings, then Security…",
data: { category: "faq", url: "/faq#reset" },
storeText: true,
},
]);
  • id is yours: 1 to 64 bytes, unique within the call. Upserting an id that already exists replaces the entry in full.
  • text (text mode) is required, up to 8 KiB. In vectors mode send vector instead, and text only together with storeText: true.
  • data is any JSON object. Keys that are declared fields must have the field’s type (null counts as absent) and can be filtered on. Any other keys are stored and returned but can’t be filtered on. Keys starting with _mk_ are refused.
  • storeText (default false) keeps the text so query and get can return it. Stored text plus data must fit in 10 KiB, or the call fails with 400 entry_too_large.

One call takes 1 to 1,000 entries. Delete by id with docs.delete(ids), up to 1,000 at a time.

const matches = await docs.query({
text: "forgot my password",
topK: 5,
filter: { category: "faq" },
includeData: true, // the default
includeText: false, // the default; returns text only if it was stored
});
// [{ id: "faq-reset", score: 0.83, data: { category: "faq", url: "/faq#reset" } }]

In vectors mode pass vector instead of text. topK defaults to 10; it can be up to 50 when includeData or includeText is set, and up to 100 when neither is.

A filter’s keys must be declared fields. A bare value means “equals”; otherwise use an operator:

OperatorMeaning
$eq, $neequals, not equal (null allowed)
$in, $ninin, not in a list (null allowed)
$gt, $gte, $lt, $lteranges, on string and number fields only
filter: { category: { $in: ["faq", "guide"] }, year: { $gte: 2024, $lt: 2026 } }

A field takes at most one lower bound ($gt or $gte) and one upper bound ($lt or $lte). The filter must be under 2 KiB as JSON. String filters compare only a value’s first 64 bytes: longer strings are stored, but two that share their first 64 bytes look the same to a filter.

Writes are asynchronous. upsert and delete return a mutationId as soon as they’re accepted, and the entries usually become searchable within a minute or two (the first write to a new collection can take longer). get doesn’t return writes that are still pending.

The simplest way to wait is upsertAndWait, or waitFor on a mutationId:

await docs.upsertAndWait([{ id: "b", text: "Changing your email" }]); // waits up to 5 minutes
// or
await docs.waitFor(mutationId, { timeoutMs: 120_000 });

Both poll docs.status(mutationId), which answers pending, done or unknown (never seen, or expired). A wait that runs out throws VectorWaitTimeoutError; the write itself still went through.

Instead of polling, a device can hear a ready notice on a Space when an upsert’s entries become searchable. A notice reaches only a Space registered as a notice Space for that environment, and only if the write named it in notify or it is the environment’s default. Otherwise there is no notice, and waiting falls back to polling.

The owner registers notice Spaces once per environment (up to 10, plus an optional default):

On the collection in the portal’s Collections section, set the notice Spaces and default for the test and live environments.

Then write and listen:

await docs.upsertAndWait([{ id: "c", text: "Two-factor sign-in" }], {
space,
notify: { space: space.id, audience: "everyone" },
});
// Or listen for every ready notice on the Space:
const off = docs.onReady(space, ({ ids, mutationId }) => refreshResults(ids));
  • notify omitted: the environment’s default notice Space, if there is one. notify: false: no notice. Naming a Space that isn’t registered fails the upsert with 400 notice_space_not_registered.
  • Audience. everyone (default) reaches every device connected to the Space, including signed-out ones. writer reaches only the writing user’s own devices, and needs a publishable-key call with a signed-in user.
  • onReady ignores notices not sent by the platform, and needs an unlocked session.

Notices are best effort: a device that wasn’t connected misses them. That’s why waitFor and upsertAndWait keep polling status underneath either way.

A collection is an index, not your database. Keep the item itself where it belongs and put a pointer to it in data: a file path, a row id, a KV key. Search, then fetch the item with the normal SDK call:

await docs.upsert([
{ id: "note-42", text: noteBody, data: { rowId: 42 } },
]);
const [best] = await docs.query({ text: "quarterly plan", topK: 1 });
if (!best?.data) return; // no match
const note = await client.db.table("notes").get(best.data.rowId as number);

Muhkoo never reads your files, rows or KV to index them. Only what you send in an upsert goes into a collection.

Each entry’s text is capped at 8 KiB, and the model only reads part of it: the English models (bge-small, bge-base, bge-large) read the first ~512 tokens of each entry, and the multilingual ones (bge-m3, qwen3-embedding-0.6b) up to 8,192. Text past that is accepted but doesn’t shape the vector. So split long documents on the device into chunks of about 1,500 characters and upsert one entry per chunk, with ids like doc-1#3:

function chunk(text: string, size = 1500): string[] {
const parts: string[] = [];
let current = "";
for (const para of text.split(/\n\s*\n/)) {
if (current && current.length + para.length > size) {
parts.push(current);
current = "";
}
// A single paragraph longer than `size` is cut into pieces.
for (let i = 0; i < para.length; i += size) {
const piece = para.slice(i, i + size);
if (current && current.length + piece.length > size) {
parts.push(current);
current = "";
}
current = current ? `${current}\n\n${piece}` : piece;
}
}
if (current) parts.push(current);
return parts;
}
const entries = chunk(docBody).map((text, i) => ({
id: `doc-1#${i}`,
text,
data: { doc: "doc-1" },
}));
await docs.upsert(entries);

Declare doc as a filterable field to search inside one document, or to group matches by document.

A collection is shared by the whole app: every key that can query it sees every entry, and a field like owner is a filter you apply, not a permission. To keep users’ entries apart, make the collection backend (publishable keys are refused with 403 backend_only) and put a function in front of it that verifies the caller and adds the filter itself:

export default {
async fetch(request, env) {
const api = (path, init) => env.MUHKOO_API.fetch(env.MUHKOO_API_URL + path, init);
const verify = await api("/api/auth/verify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ token: request.headers.get("X-Muhkoo-Session") }),
});
if (!verify.ok) return new Response("Sign in required", { status: 401 });
const { username } = await verify.json();
const { text } = await request.json();
return api("/api/vectors/notes/query", {
method: "POST",
headers: { "Content-Type": "application/json", "X-Muhkoo-Key": env.MUHKOO_APP_KEY },
body: JSON.stringify({ text, topK: 10, filter: { owner: username } }),
});
},
};

The function’s injected MUHKOO_APP_KEY carries vectors:read and vectors:write. Write entries the same way, setting owner on the server.

An agent can search collections as a tool. Pick them in the agent’s tools settings in the portal; they are saved in the agent’s tools.collections list, next to db and functions:

"tools": { "enabled": true, "collections": ["docs"] }

Only text-mode collections can be searched by agents; vectors-mode names are ignored, as are names that aren’t valid collection names. The agent gets a search_collection tool limited to the collections you listed, with their filterable fields.

LimitValue
Collections per app20 (collections still dropping count until gone)
Creates and drops10 per app per hour
Entries per upsert or delete1,000
Id length64 bytes
Text8 KiB (8,192 bytes)
Stored text plus data10 KiB (10,240 bytes)
Filterable fields10
String filter comparisonfirst 64 bytes
Filter sizeunder 2 KiB
topK50 with data or text, 100 without
Ids per get100
Dimensions (vectors mode)1,536
Notice Spaces10 per environment
WhatPrice
Queries$0.02 per million queried dimensions (each query meters the collection’s dimensions)
Stored vectors$2.10 per 100 million stored dimensions per month (dimensions × entries)
Embeddings (text-mode upserts and queries)the existing AI inference rate
Upsert, delete, get, status, noticesfree

Vector search is for paid plans only; the Free plan has no access. Paid plans have no caps. See Pricing and the client.vectors reference.