Batch

vb.batch() returns a fluent builder for /api/v1/batch. Up to 100 ops in a single request, executed inside one SQLite transaction — either every op succeeds or every op rolls back.

Why batch

• Atomicity: insert + update + delete with one conditional rollback
• Latency: one round-trip instead of N
• Determinism: server holds a transaction lock, so concurrent writers can’t interleave with your sequence

Build + run

const r = await vb.batch()
  .create("posts", { title: "first" })
  .create("posts", { title: "second" })
  .update("posts", "p_42", { published: true })
  .delete("posts", "p_99")
  .list("posts", { filter: "published = true", perPage: 5 })
  .run();

// r is BatchResult — array of per-op outcomes in submit order
r[0].status;       // 200
r[0].body;         // { id: "...", title: "first", ... }
r[3].status;       // 204 — delete
r[4].body.data;    // post[]

If ANY op returns ≥ 400 the whole transaction rolls back. The response still echoes per-op statuses so you can see which op tripped:

const r = await vb.batch()
  .create("posts", { title: "ok" })
  .create("posts", { title: "" })            // rule deny on empty title
  .run();

r[0].status;   // 422 — note that even op 0 reads as failed because
               //       the transaction rolled back.

Op shapes

batch.create<K>(collection: K, body: SchemaCreate<K>);
batch.update<K>(collection: K, id: string, body: SchemaUpdate<K>);
batch.delete(collection: string, id: string);
batch.get(collection: string, id: string);
batch.list<K>(collection: K, options?: ListOptions);

The generic K extends keyof Schema ties body types to your codegen schema. Without codegen the args fall back to unknown/AnyRecord.

Rules + auth

Batch ops respect the same per-collection rules as the underlying REST endpoints. The caller’s auth (token in vb.client.authStore) is the auth context for every op in the batch. Admin tokens bypass rules; user tokens have rules evaluated per op.

Limits

Cap	Default
Ops per batch	100
Body size	4 MB total (server-side)
Per-op timeout	inherits the standard request timeout

Exceeding 100 returns 422 before the transaction starts.

Error envelope

import { isVaultbaseError } from "@vaultbase/sdk";

try {
  await vb.batch().create("posts", {}).run();
} catch (e) {
  if (isVaultbaseError(e) && e.kind === "validation") {
    // e.details: per-op breakdown when relevant
  }
  throw e;
}

When NOT to batch

• Streaming reads — use vb.collection().iterate() instead
• Cross-collection queries that need a JOIN — write a view collection with raw SQL
• Long-running jobs — use hooks · routes · cron or the queue worker subsystem