Edges
How one item links to another, what each edge type means, and what the bin does across a link.
An edge links one item to another: it points from one item to another, such as a comment to the lease it's about. It's a record of its own, with an id, properties and a version, so writing an edge never moves either item's version.
POST /edges
Authorization: Bearer <key>
Content-Type: application/json
{
"from_id": "01a1f144-e102-7276-97a9-e93846d7cf4e",
"to_id": "01a1f144-e0da-77a3-a1c4-ead9c1e9d53c",
"edge_type": "comments-on"
}A new item can carry its edges: POST /items takes edges, an object from each edge type to the IDs it points to. If Marfa refuses any edge, it creates neither the item nor its edges.
Edge types
Every edge has an edge type, and the type sets the rules:
- Which types each end can be. An
in-collectionedge points to a container, and anin-folderedge to a folder. - How many edges an end holds, its cardinality.
many-to-onelets each from item hold at most one edge of the type, so a comment is on one item and a message in one thread.one-to-manylets each to item hold at most one, so a child has one parent.one-to-onelimits both ends, andmany-to-manyneither. - Whether its edges can loop. No edge links an item to itself, and
parent-ofandsupersedesrefuse any loop. - What the bin does across it, as Moving an item to the bin shows.
- Its labels, the headings an app shows at each end.
A write that breaks one is refused with 400 edge_constraint_violation, or 400 edge_cycle for a loop. Marfa ships eleven, which the Catalog's Edges page lists with each one's limits and how a synced folder writes it. A key whose metadata map holds edge_types=write can register more.
Choose an edge type
Start from what the link means to a person:
- One item sits under another, as a subtask under its task:
parent-of. Its children go to the bin with it. To gather items without owning them, as recipes in a collection, usein-collection, and an item can be in many collections. - An item exists only for another, as a comment, a reply or a receipt photo for an expense:
comments-onorattached-to, which make it a part. For an item that stands alone, as a note about a film, useabout. - A message belongs to a thread, as an email to its thread:
in-thread, withpositionfor its order. A conversation that holds its messages as table rows needs no edges. - One item's text links to another, a mention:
references. A device reads[[Plan]]in a note and writes areferencesedge to Plan. - An item was taken or made from another:
excerpt-offor a passage taken from it, as a highlight from a book, which carries its own text and stays when the book goes. Usederived-fromfor something made from it, as a summary from an article. - A new item replaces an old one, as this year's lease replaces last year's:
supersedes. Each item replaces at most one and is replaced by at most one.
Marfa writes in-folder itself, for the files a synced folder places.
Parts
Some items exist only for another: a comment, a reply, a scan's pages, a receipt attached to an expense. Such an item is a part, and the item it belongs to is its host. attached-to and comments-on make parts, and a registered edge type can too.
Would you look for it on its own? If not, make it a part. If you would, as with a photo in an album, use another edge type.
A part follows its host into the bin: it goes once its last host goes, and comes back when any host is restored. Listings still include parts, so an app that wants them out filters with part eq false. Archiving a host, or deleting the edge, leaves the part where it is.
Read an item's edges
An item read carries its outbound edges in edges, up to 50 of each type. Add include=backrefs for the edges that point to 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 item it points from.
Moving an item to the bin
An edge type's cascade_on_delete decides what the bin does across its edges:
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. A part goes with its last host, as Parts explains.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, 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 also choose block: while such an edge holds an item, at either end, moving that item to the bin is refused with 400 edge_constraint_violation, and details.blocking_edges names the edges. So is a delete that would take it there along a cascade. Delete the edge first. A purge is never blocked: it deletes the item's edges.
The rules behind this page are in the edges chapter of the contract.