Collections

A collection is a group of related documents — like a table in SQL, or a model in an ORM.

Each collection is defined by a schema that describes the shape of the data it holds.

📦 Defining a Collection

You define collections inside the schema object when initializing your client:

const db = createClient({
  apiKey: "your_api_key",
  schema: {
    users: {
      properties: {
        name: { type: "string", required: true },
        email: { type: "string", required: true },
        isAdmin: { type: "boolean" },
      },
    },
  },
});

This creates a users collection with three fields:

name (required string)
email (required string, unique)
isAdmin (optional boolean with a default)

✅ Schema-based, not schema-less

Unlike traditional NoSQL databases, PaperDB enforces your schema. That means:

You get validation out of the box
Required fields must be present
Unique fields are checked on insert

You do not need to write validation logic. It is automatic.

Server-backed behavior: Collections and schema validation are enforced by the API. CRUD endpoints are available for collections (see the API reference). The server implements unique checks, schema validation, and automatic indexing hints for filtered queries.

🔗 One Schema per Collection

Each collection has a single schema. If you update the schema, it applies to all documents going forward (past documents are untouched unless updated).

🔐 Unique & Required Fields

You can define fields as required in the schema. Uniqueness is enforced at insert time by passing a unique array in the request body:

// Schema definition — required only, no unique flag here
email: { type: "string", required: true }

// Insert — pass unique fields to enforce uniqueness
await db.users.insert({
  email: "alice@example.com",
  name: "Alice",
  // The SDK automatically passes unique fields from the schema
});

PaperDB will:

Block inserts if email is missing (required)
Prevent duplicates for fields marked unique: true in the schema (enforced server-side on insert)

← Databases Documents →