Vector search
What it is
Section titled “What it is”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
dimensionslong (1 to 1,536).
Create a collection
Section titled “Create a collection”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.
muhkoo vectors create <appId> docs --mode text --fields category:stringcreate waits up to 10 minutes for the collection to become ready; pass
--no-wait to return at once and check later with muhkoo vectors get <appId> docs.
You can also list collections in a provision spec:
"collections": [ { "name": "docs", "mode": "text", "fields": [ { "name": "category", "type": "string" } ] } ]provision doesn’t wait for a new collection, skips collections on a Free plan
with a warning, and stops if an existing collection’s definition differs.
await client.vectors.createCollection(appId, "docs", { mode: "text", model: "bge-base-en-v1.5", fields: [{ name: "category", type: "string" }], access: "app",});const info = await client.vectors.waitForCollection(appId, "docs"); // waits up to 10 minutesThese owner calls use your signed-in developer session, not the app key.
A definition has these parts:
| Part | Values |
|---|---|
| name | Lowercase: ^[a-z][a-z0-9_]{0,62}$ |
| mode | text 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 |
| metric | cosine (default), euclidean or dot-product |
| fields | Up to 10 filterable fields, each string, number or boolean |
| access | app (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.
Add entries
Section titled “Add entries”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, },]);idis 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 sendvectorinstead, andtextonly together withstoreText: true.datais 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 soqueryandgetcan return it. Stored text plusdatamust fit in 10 KiB, or the call fails with400entry_too_large.
One call takes 1 to 1,000 entries. Delete by id with docs.delete(ids), up to
1,000 at a time.
Search
Section titled “Search”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:
| Operator | Meaning |
|---|---|
$eq, $ne | equals, not equal (null allowed) |
$in, $nin | in, not in a list (null allowed) |
$gt, $gte, $lt, $lte | ranges, 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.
Know when it’s searchable
Section titled “Know when it’s searchable”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// orawait 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.
Ready notices
Section titled “Ready notices”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.
muhkoo vectors notices <appId> docs --env live --spaces <spaceId> --default <spaceId>const space = await client.space.joinChannel("docs-updates");await client.vectors.setNotices(appId, "docs", "live", { spaces: [space.id], defaultSpace: space.id,});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));notifyomitted: the environment’s default notice Space, if there is one.notify: false: no notice. Naming a Space that isn’t registered fails the upsert with400notice_space_not_registered.- Audience.
everyone(default) reaches every device connected to the Space, including signed-out ones.writerreaches only the writing user’s own devices, and needs a publishable-key call with a signed-in user. onReadyignores 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.
Point at your data
Section titled “Point at your data”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 matchconst 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.
Long documents
Section titled “Long documents”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.
Per-user separation
Section titled “Per-user separation”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.
Agents
Section titled “Agents”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.
Limits and pricing
Section titled “Limits and pricing”| Limit | Value |
|---|---|
| Collections per app | 20 (collections still dropping count until gone) |
| Creates and drops | 10 per app per hour |
| Entries per upsert or delete | 1,000 |
| Id length | 64 bytes |
| Text | 8 KiB (8,192 bytes) |
Stored text plus data | 10 KiB (10,240 bytes) |
| Filterable fields | 10 |
| String filter comparison | first 64 bytes |
| Filter size | under 2 KiB |
topK | 50 with data or text, 100 without |
Ids per get | 100 |
| Dimensions (vectors mode) | 1,536 |
| Notice Spaces | 10 per environment |
| What | Price |
|---|---|
| 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, notices | free |
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.