CleaveDB LogoBack to Home
Getting Started

Tutorial: Building with CleaveDB

SUGGEST BONDS

As data models grow, documents often reference each other through foreign key fields, string IDs, or semantic concepts without having explicit graph bonds defined. The SUGGEST BONDS command scans your documents and intelligently proposes missing relationships.

Inspecting relationship suggestions

Run SUGGEST BONDS to scan for unlinked candidate pairs:

CleaveQLExample · Request bond suggestions
SUGGEST BONDS

The engine returns a ranked list of suggestions with confidence scores:

CleaveQLExample · Engine response format
{
  "status": "ok",
  "count": 2,
  "suggestions": [
    {
      "source": "logs:l3",
      "target": "staff:c",
      "confidence": 0.95,
      "reason": "Field 'owner' references staff:c"
    },
    {
      "source": "logs:l1",
      "target": "staff:a",
      "confidence": 0.75,
      "reason": "Field 'user' matches the id of staff:a"
    }
  ]
}

Pairs that are already bonded in either direction are excluded from the output.

Detection signals & confidence scores

CleaveDB combines heuristic field matching with AI vector embedding proximity to score potential relationships:

SignalConfidenceExample Pattern
Full document ID match0.95Field holds a qualified ID like {"owner": "staff:c"}
Cross-bucket ID match0.75Field holds a bare ID like {"user": "a"} matching staff:a
AI Vector Embedding similarity> 0.50Cosine similarity in _embeddings demonstrates semantic affinity

Review & bond workflow

Accepting a suggestion is as simple as creating the bond with BOND:

CleaveQLExample · Interactive suggestion lifecycle
-- 1. Inspect what relationships are missing
SUGGEST BONDS

-- 2. Accept a high-confidence recommendation
BOND "logs:l1" TO "staff:a" AS "by"

-- 3. Verify suggestion is dismissed
SUGGEST BONDS

-- 4. Query across the newly formed relationship
FIND "by" OF "logs:l1"

Once bonded, the recommendation is dismissed and no longer appears in future SUGGEST BONDS results.