Relationships

Overview

Relationships connect entities to each other. They're stored as part of the entity manifest and versioned along with everything else.

A relationship has:

predicate -- The type of connection (e.g. contains, parent, references)
peer -- The target entity ID
peer_type -- Optional type hint for the target
peer_label -- Optional display name
properties -- Optional metadata on the relationship itself

Creating Relationships

At Entity Creation

POST /entities
{
  "type": "file",
  "properties": { "name": "Document" },
  "collection_id": "01JCOL...",
  "relationships": [
    { "predicate": "parent", "peer": "01JFOLDER..." }
  ]
}

On an Existing Entity

PUT /entities/:id
{
  "expected_cid": "bafyreig...",
  "relationships_add": [
    { "predicate": "references", "peer": "01JOTHER..." }
  ]
}

Common Predicates

Predicate	Direction	Meaning
`contains`	Parent → Child	Parent contains the child entity
`parent`	Child → Parent	Child belongs to this parent
`references`	Any	General reference link
`member_of`	User → Collection	User membership in collection

Querying Relationships

Use the Argo query DSL for graph traversal:

@01JENTITY... -[contains]{,3}-> type:file

This starts at a specific entity and traverses up to 3 hops of contains relationships to find files.

See Argo Queries for the full query syntax.