Documents

Code

Write it. Read it. Same engine.

INSERT INTO logs DOCUMENT (body) VALUES ({"level":"warn","ip":"10.0.0.1","path":"/admin"});

SELECT body->>'ip', body->>'path' FROM logs WHERE body->>'level' = 'warn' ORDER BY created_at DESC;

Build it

End-to-end walkthrough.

Four steps from empty database to a real documents workload — each step shows the exact code and explains what the engine is doing.

1. Step 1

   1. Create the document collection

   DOCUMENT collections still have an id and created_at — what they trade is column DDL for the freedom to put any shape in body. Indexes on JSON paths are first-class: body->>'kind' is indexed exactly like a typed column.

   CREATE TABLE events DOCUMENT (
     id          UUID PRIMARY KEY DEFAULT gen_uuid(),
     body        JSONB NOT NULL,
     created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
   );
   
   -- Index a hot path for fast filtering.
   CREATE INDEX idx_events_kind ON events ((body->>'kind'));

2. Step 2

   2. Insert mixed payloads

   Three different shapes, same collection. No migration needed when a new event kind shows up — write the row, query by kind later when reporting needs it.

   INSERT INTO events DOCUMENT (body) VALUES
     ({"kind":"signup","user_id":42,"plan":"nano"}),
     ({"kind":"login","user_id":42,"ip":"1.2.3.4","ua":"chrome/120"}),
     ({"kind":"webhook.stripe","event_id":"evt_1","amount":1900});

3. Step 3

   3. Query by JSON path

   JSON path operators (->> for text, -> for nested) are SQL-native. The optimiser uses the index on body->>kind to skip a full scan, even though the column was never declared.

   SELECT
     body->>'kind'  AS kind,
     COUNT(*)       AS occurrences
   FROM events
   WHERE created_at > now() - INTERVAL '24 hours'
     AND body->>'user_id' = '42'
   GROUP BY kind
   ORDER BY occurrences DESC;

4. Step 4

   4. Promote a hot field to a column

   When a path goes from "occasionally queried" to "always filtered on", promote it to a generated column. RedDB stores it once and lets the optimiser use it like a regular column — no change at the application layer.

   ALTER TABLE events ADD COLUMN kind TEXT
   GENERATED ALWAYS AS (body->>'kind') STORED;
   
   CREATE INDEX idx_events_kind_created ON events (kind, created_at DESC);

Showcases

What documents can do once you bring the rest of the engine in.

Cross-model correlation, algorithm flex, multi-model patterns — things that take a stack of services elsewhere.

CREATE TABLE projects (
  id      UUID PRIMARY KEY,
  org_id  UUID NOT NULL,
  name    TEXT NOT NULL,
  custom  JSONB DEFAULT '{}'::jsonb
);

-- Promote the most-queried tenant's hot field to a column.
ALTER TABLE projects ADD COLUMN priority TEXT
  GENERATED ALWAYS AS (custom->>'priority') STORED;

CREATE INDEX idx_projects_org_priority
  ON projects (org_id, priority)
  WHERE custom->>'priority' IS NOT NULL;

-- App-tier code keeps writing free-form JSON; the report query above
-- now hits a composite BTree.

SELECT
  u.email,
  COUNT(*) FILTER (WHERE e.body->>'type' = 'invoice.paid')      AS paid,
  COUNT(*) FILTER (WHERE e.body->>'type' = 'invoice.failed')    AS failed,
  SUM((e.body->'data'->'object'->>'amount')::int) FILTER (
    WHERE e.body->>'type' = 'invoice.paid'
  ) AS total_cents
FROM stripe_events e
JOIN users u ON u.stripe_customer_id = e.body->>'customer'
WHERE e.created_at > now() - INTERVAL '30 days'
GROUP BY u.email
ORDER BY total_cents DESC NULLS LAST;

Recipes

Common patterns, real driver code.

INSERT INTO audit_log DOCUMENT (body) VALUES
  ('{"actor":"user:42","action":"role.grant","target":"user:99","meta":{"role":"admin"}}');

SELECT body->>'actor', body->>'action', created_at
FROM audit_log
WHERE body->>'target' = 'user:99'
ORDER BY created_at DESC LIMIT 50;

app.post('/webhooks/stripe', async (req) => {
  const event = JSON.parse(req.rawBody)
  await db.query(
    'INSERT INTO stripe_events DOCUMENT (body) VALUES ($1)',
    [event],
  )
  return new Response('ok')
})

CREATE TABLE projects (
  id      UUID PRIMARY KEY,
  name    TEXT NOT NULL,
  custom  JSONB DEFAULT '{}'::jsonb
);
SELECT name, custom->>'priority' FROM projects WHERE custom->>'tenant' = 'acme';

vs

How RedDB documents compare.

Pairs with

Documents earns more next to these.

The data models documents compose with — a click away.

• relational

  Tables →

  Join an `events` document collection to a `users` table by `body->>"user_id"` — same SQL planner, no glue.

• semantic

  Vectors →

  Documents make great RAG source content — auto-embed a `body` field and the vector index lives next to the JSON.

• edges

  Graphs →

  Documents reference graph nodes via `body->>"entity_id"` — traversal expands documents in the same query.

Explore

Every other data model on RedDB.

One engine, 9 first-class data models. Mix as needed.

• relational

  Tables →

  Postgres-wire SQL with indexes, joins, transactions.

• edges

  Graphs →

  Native edges and traversals — multi-hop without a side-car.

• semantic

  Vectors →

  Auto-embed on insert, similarity search, no vector DB to sync.

• fast state

  Key-Value →

  Configuration, feature flags, hot keys — millisecond reads.

• tiered TTL

  Cache →

  Tiered blob cache built into the engine: L1 memory + L2 durable.

• metrics

  Time-series →

  Retention, downsampling, native window queries.

• workflows

  Queues →

  FIFO, priority, consumer groups — durable workflow primitives.

• sketches

  Probabilistic →

  HyperLogLog, Count-Min Sketch, Cuckoo Filter — bounded-memory analytics.