client.vectors
client.vectors is your app’s vector search: collections of entries you
search by meaning. In text mode Muhkoo makes the vectors from your text; in
vectors mode you send your own. See the Vector search guide
for the concepts, limits and pricing.
Data calls are authorized by the app key; the app and environment come from
the key, so test and live keys reach separate entries. A collection with
backend access refuses the browser-safe publishable key. The owner calls
(create, drop, notices) use your signed-in developer session and are owner-only.
The SDK does no validation of its own: server errors ({ error, code }) reach you
as HttpError.
collection(name)
Section titled “collection(name)”collection(name: string): VectorCollectionReturns a handle on the named collection. Cheap to make; it holds no state beyond its name.
const docs = client.vectors.collection("docs");Collection methods
Section titled “Collection methods”upsert(entries, opts?)
Section titled “upsert(entries, opts?)”upsert(entries: VectorEntryInput[], opts?: VectorUpsertOptions): Promise<VectorWriteResult>Adds or replaces entries (1 to 1,000 per call; an existing id is replaced in
full). Returns once the write is accepted; entries usually become searchable
within a minute or two. Needs vectors:write.
interface VectorEntryInput { id: string; // 1-64 bytes, unique within the call text?: string; // text mode: required, up to 8,192 bytes vector?: number[]; // vectors mode: required, exactly `dimensions` numbers data?: Record<string, unknown>; // declared fields are filterable; others are stored only storeText?: boolean; // keep the text so query/get can return it (default false)}
interface VectorUpsertOptions { notify?: VectorNotify;}
type VectorNotify = false | { space?: string; audience?: VectorAudience };type VectorAudience = "everyone" | "writer";
interface VectorWriteResult { mutationId: string; count: number;}notify omitted sends a ready notice to the environment’s default notice Space,
if it has one; false sends none; { space } must name a registered notice
Space. See Ready notices.
query(input)
Section titled “query(input)”query(input: VectorQueryInput): Promise<VectorMatch[]>Returns the nearest entries to a text (text mode) or a vector (vectors mode).
Needs vectors:read.
interface VectorQueryInput { text?: string; vector?: number[]; topK?: number; // default 10; max 50 with data or text, 100 without filter?: Record<string, unknown>; // declared fields; $eq $ne $in $nin $lt $lte $gt $gte includeData?: boolean; // default true includeText?: boolean; // default false; text only if it was stored}
interface VectorMatch { id: string; score: number; data?: Record<string, unknown>; text?: string;}String filters compare only a value’s first 64 bytes.
get(ids, opts?)
Section titled “get(ids, opts?)”get(ids: string[], opts?: { includeVector?: boolean }): Promise<VectorEntry[]>Entries by id (1 to 100). Ids that aren’t found are left out, and so are writes
still pending. Needs vectors:read.
interface VectorEntry { id: string; data: Record<string, unknown>; text?: string; // only if stored vector?: number[]; // only with includeVector}delete(ids)
Section titled “delete(ids)”delete(ids: string[]): Promise<VectorWriteResult>Removes entries by id (1 to 1,000). Asynchronous, like upsert, and sends no
notice. Needs vectors:write.
status(mutationId)
Section titled “status(mutationId)”status(mutationId: string): Promise<VectorWriteState>
type VectorWriteState = "pending" | "done" | "unknown";The state of a write. unknown means never seen or expired (pending for over 60
minutes). done is kept for at least 24 hours; don’t rely on unknown after
that. Needs vectors:read.
waitFor(mutationId, opts?)
Section titled “waitFor(mutationId, opts?)”waitFor(mutationId: string, opts?: { space?: Space; timeoutMs?: number }): Promise<void>Resolves once the write is searchable: on its ready notice (with space) or when
status answers done. It polls status either way, because notices are best
effort. The notice only arrives if space is a registered notice Space for the
environment, named in the write’s notify.space or set as the default; otherwise
the wait completes by polling.
Rejects with an Error (“Unknown mutation …”) if status answers unknown, and
with VectorWaitTimeoutError after timeoutMs
(default 300,000 ms, 5 minutes).
upsertAndWait(entries, opts?)
Section titled “upsertAndWait(entries, opts?)”upsertAndWait( entries: VectorEntryInput[], opts?: VectorUpsertOptions & { space?: Space; timeoutMs?: number },): Promise<VectorWriteResult>upsert, then waitFor its mutation. With space it listens before sending,
so a notice that beats the HTTP response still counts. An upsert error is
rethrown at once.
onReady(space, handler)
Section titled “onReady(space, handler)”onReady(space: Space, handler: (e: VectorReadyEvent) => void): () => void
interface VectorReadyEvent { collection: string; ids: string[]; mutationId: string;}Listens on an open Space for this collection’s ready notices. Only notices the
platform sent reach handler; a member publishing the same subject is ignored.
Needs an unlocked session. Returns the unsubscribe.
Managing collections
Section titled “Managing collections”These calls use the developer session and are owner-only, like the database tables API.
listCollections(appId)
Section titled “listCollections(appId)”listCollections(appId: string): Promise<VectorCollectionInfo[]>The app’s collections, sorted by name.
getCollection(appId, name)
Section titled “getCollection(appId, name)”getCollection(appId: string, name: string): Promise<VectorCollectionInfo>One collection. A missing or badly named one is 404 collection_not_found.
createCollection(appId, name, definition)
Section titled “createCollection(appId, name, definition)”createCollection( appId: string, name: string, definition: VectorCollectionDefinition,): Promise<VectorCollectionInfo>Creates a collection in both environments. Asynchronous: it answers with status
creating; use waitForCollection. Repeating it with the same definition
returns the existing collection; a different definition is 409
collection_exists. Definitions never change: drop and recreate.
type VectorCollectionDefinition = | { mode: "text"; model?: string; // default "bge-base-en-v1.5" metric?: "cosine" | "euclidean" | "dot-product"; fields?: VectorFieldDefinition[]; access?: "app" | "backend"; } | { mode: "vectors"; dimensions: number; // 1-1536 metric?: "cosine" | "euclidean" | "dot-product"; fields?: VectorFieldDefinition[]; access?: "app" | "backend"; };
interface VectorFieldDefinition { name: string; type: "string" | "number" | "boolean";}Models: bge-small-en-v1.5 (384), bge-base-en-v1.5 (768, default),
bge-large-en-v1.5 (1024), bge-m3 (1024, multilingual), qwen3-embedding-0.6b
(1024, multilingual).
waitForCollection(appId, name, opts?)
Section titled “waitForCollection(appId, name, opts?)”waitForCollection(appId: string, name: string, opts?: { timeoutMs?: number }): Promise<VectorCollectionInfo>Polls getCollection every 2 s until status is ready. Rejects with
VectorCollectionFailedError on failed, and
with Error("Timed out waiting for collection <name>") after timeoutMs
(default 600,000 ms, 10 minutes).
dropCollection(appId, name)
Section titled “dropCollection(appId, name)”dropCollection(appId: string, name: string): Promise<void>Drops a collection and its entries in both environments. Asynchronous; the
collection shows status dropping until it is gone. Safe to repeat: a 503
vectors_unavailable means the drop couldn’t start, and calling again is the
remedy.
setNotices(appId, name, env, notices)
Section titled “setNotices(appId, name, env, notices)”setNotices( appId: string, name: string, env: "live" | "test", notices: VectorNotices,): Promise<VectorNotices & { env: "live" | "test" }>
interface VectorNotices { spaces: string[]; // up to 10 Space ids of this app and environment defaultSpace: string | null; // null or one of `spaces`}Sets which Spaces receive ready notices for one environment.
VectorCollectionInfo
Section titled “VectorCollectionInfo”interface VectorCollectionInfo { name: string; mode: "text" | "vectors"; model: string | null; // null in vectors mode dimensions: number; metric: string; fields: VectorFieldDefinition[]; access: "app" | "backend"; createdAt: number; status: "creating" | "ready" | "failed" | "dropping"; envs: { live: VectorEnvInfo; test: VectorEnvInfo };}
interface VectorEnvInfo { status: "creating" | "ready" | "failed" | "dropping"; entries: number | null; // last count read; null before the first notices: VectorNotices; error: string | null; // why, when status is "failed"}Errors
Section titled “Errors”VectorWaitTimeoutError
Section titled “VectorWaitTimeoutError”Thrown by waitFor and upsertAndWait when the wait runs out. The write itself
was accepted; check status(err.mutationId) later.
import { VectorWaitTimeoutError } from "@muhkoo/connect";
try { await docs.upsertAndWait(entries);} catch (err) { if (err instanceof VectorWaitTimeoutError) later(err.mutationId); else throw err;}VectorCollectionFailedError
Section titled “VectorCollectionFailedError”Thrown by waitForCollection when creation failed. err.info is the
VectorCollectionInfo; info.envs.live.error or info.envs.test.error says why.
HttpError codes
Section titled “HttpError codes”Server errors arrive as HttpError, with the
body’s code. The 402s with owner_payment_past_due or user_plan_required
arrive as its subclass PaymentRequiredError.
| Status | code | When |
|---|---|---|
400 | invalid_collection | Bad collection name on a data call |
400 | invalid_entries | Bad entries, or bad ids on get / delete |
400 | entry_too_large | Stored text plus data over 10,240 bytes |
400 | invalid_query | Bad query or filter |
400 | invalid_mutation | status without a mutation id |
400 | notice_space_not_registered | notify.space isn’t a notice Space for the environment |
400 | no_notice_space | notify without space, and no default notice Space |
400 | writer_needs_session | audience: "writer" without a publishable-key call and a signed-in user |
400 | invalid_definition | Bad definition or collection name on create |
400 | invalid_notices, notice_space_invalid | Bad notices, or a Space not of this app and environment |
402 | (none; requiresPaidTier) | The app owner is on the Free plan |
402 | vector_quota | Over quota |
402 | owner_payment_past_due | The owner’s payment is past due; upserts are refused, queries still work |
402 | user_plan_required | The app takes paid Muhkoo accounts only |
403 | backend_only | A publishable key on a backend collection |
403 | forbidden | The key’s app or environment doesn’t match the collection |
403 | The credential lacks vectors:read / vectors:write | |
404 | collection_not_found | No such collection, or it is being dropped |
409 | collection_not_ready | The collection is creating or failed (body has status) |
409 | collection_exists | Create with a different definition |
409 | collection_dropping | Create while a drop runs |
409 | collection_limit | 20 collections already |
429 | vector_rate_limited | Over 10 creates and drops per app per hour (Retry-After) |
502 | vector_backend_error | The search backend failed |
502 | embedding_failed | Turning text into a vector failed |
503 | vector_backend_busy | The collection is being updated; retry after Retry-After |
503 | vectors_unavailable | Create or drop couldn’t run; a repeated drop is safe |