Tutorial: Building with CleaveDB

Edge Directions

In real graphs, relationships have directionality. CleaveQL uses natural English prepositions—TO, FROM, and WITH—to specify the traversal orientation of each bond in a FIND PATTERN query.

Direction syntax overview

1. Outgoing bonds (TO)

Use TO when the left document is the source that originated the bond:

FIND PATTERN staff AS x LINKED VIA "manages" TO staff AS y

This resolves all relationships where x points directly to y with label "manages".

2. Incoming bonds (FROM)

Use FROM when you want to look backward along an incoming edge:

FIND PATTERN staff AS x LINKED VIA "manages" FROM staff AS boss

Here, CleaveDB finds who manages x by walking incoming "manages" bonds back to the manager document aliased as boss.

3. Mutual / Undirected bonds (WITH)

When documents are connected with mutual bonds (e.g., BOND "staff:ana" AND "staff:eve" AS MUTUAL "peer"), use WITH to match in both directions:

-- Setup mutual bond:
BOND "staff:ana" AND "staff:eve" AS MUTUAL "peer"

-- Query both orientations:
FIND PATTERN staff AS x LINKED VIA "peer" WITH staff AS y

This query returns symmetric pairs from both perspectives (e.g. x = ana, y = eve and x = eve, y = ana).