Edges
How one item links to another, and how the link's type decides what happens when either item goes to the bin.
An edge links one item, its source, to another, its target, such as a note about a book. It's a record of its own, with its own id, properties and version, so writing an edge never moves either item's version.
POST /edges
Content-Type: application/json
{ "source_id": "<note id>", "target_id": "<book id>", "edge_type": "about" }A new item can carry its edges in the same write: POST /items takes edges, an object from each edge type to the IDs of the targets. If the instance refuses any edge, it creates neither the item nor its edges.
Edge types
Every edge has an edge type, which sets the rules its edges follow:
- Which types each end can be. Most shipped edge types join any two items, but an
in-collectionedge must point at a container and anin-folderedge at a folder. A registered edge type can name its own. - How many edges an end holds. A child has one parent, a message is in one thread, and a new item supersedes one old one.
- Whether its edges can loop. No edge links an item to itself.
parent-ofandsupersedesrefuse an edge that would close a loop, and so doattached-toandcomments-on, through any mix of the two. - What the bin does across it, as Moving an item to the bin shows.
- Its labels, the headings an app shows at each end, such as Children and Parent.
A write that breaks one is refused with 400 edge_constraint_violation, or 400 edge_cycle for a self-link or a loop of parent-of or supersedes.
Marfa ships eleven edge types, and a key that may write edge types can register more. The Catalog's Edges page lists each one's labels and limits.
Where an item sits
| Edge type | Use it when | Example |
|---|---|---|
parent-of | An item sits under another in a hierarchy. The source is the parent, and an item has at most one parent. | A task parent-of its subtasks |
in-collection | You gather items into a container, in order. | A recipe in a collection of dinners |
in-thread | Messages make one conversation, in order. A message is in at most one thread. | An email in its thread |
attached-to | An item, such as a file or a page of a scan, exists only for another. The source is the attachment. | A receipt photo attached to an expense |
comments-on | An item is a comment on another item, or a reply to a comment. | A reply to a comment on a draft |
in-folder | A synced folder writes it for you, with the file's path. | A note in your Notes folder |
How two items relate
| Edge type | Use it when | Example |
|---|---|---|
about | One item is on the subject of another. | A note about a book |
references | One item's text links to or embeds another, or a program links them for its own use. | A note that links to another note |
excerpt-of | An item is a passage taken from another, such as a highlight or a clip, and carries its own text. | A highlight from a book |
derived-from | An item was made from another, and both stay valid. | A summary written from an article |
supersedes | A new item replaces an old one. | This year's lease superseding last year's |
Read an item's edges
An item read carries its outbound edges in edges, keyed by edge type, up to 50 of each type. Add include=backrefs for the edges that point at it, and include=neighbors for the items at the other ends. List an item's edges and List an item's backrefs page through the rest.
A key reads an edge only when it may read the edge type, which its edge map grants, and the source item.
Moving an item to the bin
An edge type's cascade_on_delete decides what the bin does across its edges. The shipped edge types use three of the four choices:
cascade, onparent-of. Moving a parent to the bin takes its children with it, at every depth, and never the other way.with-hosts, onattached-toandcomments-on. The source is a part of its target, its host. A part goes to the bin once its last host does, comes back when any host is restored, and is purged with the host that took it once no host is left. Archiving a host, or deleting the edge, leaves the part where it is.orphan, on the other eight. The other item stays active, and so does the edge.
So a note moved to the bin takes its child note and its comments with it, and leaves the book it's about where it is.
The child note goes too, because parent-of cascades. The book stays, because about orphans.
The child note goes too, because parent-of cascades. The book stays, because about orphans.
core.noteparent-of cascadecore.noteabout orphancore.media.bookA registered edge type can choose any of the four, including block, which refuses to move either end into the bin while the edge holds it. A purge is never blocked: it deletes the item's edges at both ends.
The rules behind this page are in the edges chapter of the contract.