Collections

Collections provide schemaless document storage. Documents are JSON objects with an auto-generated id field, stored in the framework's internal _chimpbase_collections table. No migrations needed.

Insert

const id = await ctx.collection.insert("notes", {
  body: "First note",
  todoId: 42,
  createdAt: new Date().toISOString(),
});
// id: "550e8400-e29b-41d4-a716-446655440000"

Returns the generated document ID (UUID).

Find

// Find with filter
const notes = await ctx.collection.find("notes", { todoId: 42 });

// Find with limit
const recent = await ctx.collection.find("notes", {}, { limit: 10 });

Find One

const note = await ctx.collection.findOne("notes", { id: "550e8400-..." });
// returns the document or null

Update

const updated = await ctx.collection.update(
  "notes",
  { id: "550e8400-..." },
  { body: "Updated note" },
);
// returns number of documents updated

Delete

const deleted = await ctx.collection.delete("notes", { id: "550e8400-..." });
// returns number of documents deleted

// Delete all in a collection
const deletedAll = await ctx.collection.delete("notes");

List Collections

const names = await ctx.collection.list();
// ["notes", "snapshots", "preferences"]

When to Use Collections vs. SQL

Use collections when:

• You need flexible document storage without migrations
• Schema evolves frequently
• You're building plugins that need generic storage

Use ctx.db.query() when:

• You need relational queries (joins, aggregations)
• You need indexes for performance
• Your data has a fixed schema

REST Collections Plugin

The @chimpbase/rest-collections plugin automatically exposes collections as REST APIs:

import { restCollections } from "@chimpbase/rest-collections";

restCollections({
  basePath: "/api",
  collections: {
    notes: {
      collection: "todo_notes",
      filterableFields: { todoId: "number" },
      writableFields: ["body", "todoId"],
    },
  },
});

See the REST Collections page for details.