Tutorial: Building with CleaveDB
Relationships & References (BOND & LINK) — Overview
In traditional relational databases, connecting data across different tables requires foreign keys, junction tables, and expensive multi-table JOIN operations. CleaveDB replaces this friction with native graph relationships and references.
Two Distinct Connection Mechanisms
CleaveDB provides two distinct relationship mechanisms with different architectures, semantics, and storage engines:
1. Graph Bonds (BOND)
Rich semantic graph edges stored in _bonds. A bond requires an explicit relationship label via AS "<label>" (e.g. AS "friend"). Supports weights, conditions, TTL, mutual connections, and cascading deletes. Removed with SEVER.
2. Document Links (LINK)
Direct structural document pointers or external URL references stored in _links. Relationship label is optional (defaults to "linked"). Can reference external web URLs (https://...). Cannot take graph modifiers. Removed with UNLINK.
| Feature | BOND (Graph Relationship) | LINK (Document / URL Reference) |
|---|---|---|
| Primary Purpose | Semantic graph relationships with meaning (edges) | Direct document / external URL references |
| Relationship Label | Required via AS "<label>" | Optional (defaults to "linked") |
| Internal Storage | _bonds | _links |
| External Web URLs | No (internal documents only) | Yes (https://...) |
| Weights & Modifiers | WITH, IF, EXPIRING, EXCLUSIVELY | No (rejected by parser) |
| Removal Command | SEVER <doc1> FROM <doc2> | UNLINK <doc1> FROM <doc2> |
Explore the relationship & reference topics
Each lesson provides practical CleaveQL examples covering the complete relationship and reference toolkit:
- Basic bonds (BOND): connect documents with required directed semantic labels.
- Document & URL links (LINK): lightweight document references and external web URLs.
- Mutual bonds: create symmetric, bidirectional connections in both directions.
- Conditional bonds: create dormant edges that activate based on document field values.
- Expiring bonds: set automatic time-to-live expirations on temporary relationships.
- Exclusive bonds: enforce single-edge constraints per label and source document.
- Cascade on delete: configure automatic deletion cascades when source documents are drained.
- Confidence & affinity: attach probabilistic scores and affinity weights to graph edges.
- Removing relationships (SEVER & UNLINK): dedicated removal commands and healing.