Tutorial: Building with CleaveDB

Basic Bonds (BOND)

A graph bond is a directed, semantic relationship pointing from an existing source document to an existing target document. In CleaveQL, bonds can connect documents within the same bucket or span across completely different buckets, and are stored in the dedicated _bonds catalog.

Creating a directed bond

Use BOND with TO and assign a semantic relationship label using AS:

BOND "users:jane" TO "users:juan" AS "friend"

This creates a directed graph edge labeled "friend" from Jane to Juan. You can query Jane's friends using FIND "friend" OF "users:jane".

Cross-bucket bonds

Bonds naturally link records between disparate collections without requiring foreign key schemas or junction tables:

BOND "orders:ord_901" TO "users:jane" AS "purchased_by"

The relationship lives directly in the document graph index, allowing instantaneous traversal between orders and user accounts.

Multi-target bonding

You can connect a source document to several targets simultaneously using comma-separated targets or TO ANY(...):

-- Comma-separated targets
BOND "users:jane" TO "users:juan", "users:pedro" AS "knows"

-- Using ANY(...)
BOND "users:jane" TO ANY("tag:sql", "tag:rust", "tag:ai") AS "skill"

CleaveDB provisions graph pointers to each listed document in an atomic batch.