Tutorial: Building with CleaveDB

Bond History (FIND HOW)

In dynamic graphs, relationships evolve constantly—people change managers, access grants expire, and ownership transfers. Traditional databases only store the current state unless you write complex custom audit triggers. CleaveDB tracks relationship lifecycle events natively in its Write-Ahead Log (WAL) and allows you to inspect relationship drift using FIND HOW.

Querying bond drift over time

The FIND HOW THE "label" OF "document_id" CHANGED BETWEEN "start" AND "end" command inspects historical mutations for a specific document and relationship type:

-- Create management bonds:
BOND "staff:ana" TO "staff:bob" AS "manages"
BOND "staff:ana" TO "staff:cam" AS "manages"

-- Inspect how Ana's "manages" relationships changed:
FIND HOW THE "manages" OF "staff:ana" CHANGED BETWEEN "yesterday" AND "tomorrow"

CleaveDB returns the sequence of relationship events recorded in the timeline:

[
  { "action": "BOND", "target": "staff:bob" },
  { "action": "BOND", "target": "staff:cam" }
]

Tracking bond deletions (SEVER)

When a bond is removed with SEVER, the deletion event is also appended to the historical ledger:

-- Sever Ana's management of Cam:
SEVER "staff:ana" FROM "staff:cam" AS "manages"

-- Query the full historical interval:
FIND HOW THE "manages" OF "staff:ana" CHANGED BETWEEN "2000-01-01" AND "2999-01-01"

The returned history now includes the SEVER event alongside the original creations:

[
  { "action": "LINK", "target": "staff:bob" },
  { "action": "LINK", "target": "staff:cam" },
  { "action": "SEVER", "target": "staff:cam" }
]

Time window expressions

The BETWEEN clause accepts both natural language offsets and explicit ISO-8601 timestamps:

• "yesterday" AND "tomorrow": relative window around current server time.
• "2026-01-01" AND "2026-12-31": calendar year inspection.
• "2026-10-01T08:00:00Z" AND "2026-10-01T17:00:00Z": precise operational shift window.