Relationship

​

For

A relationship has a type, a start, an end and properties. The Shape declares which types may join which entity types. A relationship has its own id and its own revision, apart from the entities at its ends. Search and traversal read relationships, so a missing relationship hides one entity from the other.

​

Use when

• You state that one entity relates to another, such as a person who works at an organization.
• You list what an entity is connected to, in one direction or both.
• You change the properties of a relationship, or remove one relationship and keep both entities.
• You must connect another entity to what a duplicate was connected to.

​

Not this

• Name, description or properties of an entity: use card Entity.
• A reviewed set of new and changed entities and relationships: use card workspace.
• Two entities that are one thing: use recipe resolve-duplicates.

​

Rules

1. relationship.1 The Shape decides which relationships exist. Enforced: validate and submit report the error relationship_declaration_missing when no Shape declares the type for those two entity types, and apply nothing. Your job: read the relationships of the Shape with penumbra shapes show before you stage one.
2. relationship.2 A relationship is created only in a workspace. Your job: stage it with penumbra graph workspace capture and submit the workspace (card rule workspace.2). Penumbra has no command that creates one outside a workspace, so it does not exist in the Graph until the submit returns applied.
3. relationship.3 Name each end by its id. Enforced: an end given as a name that matches several entities is refused with node_ambiguous, and the reply lists the candidates. When the name search reaches its limit, the refusal is node_resolution_incomplete. Your job: with duplicate names in the project, pass the id of the entity you mean.
4. relationship.4 The ends and the type of a relationship never change. Your job: to point a connection at another entity, stage a new relationship and remove the old one. Penumbra has no operation that changes an end of an existing relationship.
5. relationship.5 Change the properties of an existing relationship in a workspace. Check it out with penumbra graph workspace hydrate and the flag --edge, then stage a patch with penumbra graph workspace modify. Enforced: validate reports patch_missing when the checked-out relationship has no patch. Your job: know that the patch merges into the properties it has, so a property you leave out keeps its value.
6. relationship.6 Deleting an entity deletes the relationships that touch it, and restoring the entity does not bring them back (card rule entity.3). Your job: before you delete an entity, write down the type, direction, other end and properties of each relationship. To remove one relationship only, run penumbra graph workspace hydrate with --edge <id> and --intent delete. Penumbra has no command that restores one relationship. Stage it again.
7. relationship.7 A relationship cannot touch a deleted entity. Enforced: validate reports the error endpoint_deleted for a staged relationship whose end is deleted. Your job: restore the entity first, or choose another end.
8. relationship.8 Cite each relationship you can support. Your job: pass citations on the relationship itself, as card rule passage.2 says. Penumbra does not copy the citations of its ends or of an older relationship to a new one. A moved relationship has no citation until you cite it.

​

Failure signs

• A stage call fails with node_ambiguous: rule relationship.3, and problem same-name-two-entities.
• Validate reports relationship_declaration_missing: rule relationship.1.
• A stage call fails with relationship_ambiguous: several Shapes declare the type for these entities. Name the Shape in the shape field of the relationship.
• penumbra graph delete is refused with too_many_relationships: the entity has more than 100 relationships. Delete it through a workspace with penumbra graph workspace hydrate and --intent delete.
• An entity you restored has no connections: rule relationship.6.
• Two entities are one thing and each holds some connections: problem merge-duplicates.

​

Doors

A Program stage takes only the type, the start and the end. It cannot set properties or citations on a relationship. Use the CLI or the full catalog for that. The default catalog has no call that changes the properties of a relationship.

​

The CLI word

The CLI calls a relationship an edge.

​

HTTP reference

• List graph nodes
• Get graph node
• Get node history
• List graph edges
• Get graph edge
• Get edge history
• Count graph records
• Traverse graph
• List graph commits
• Get graph commit

​

Keep going

Entity · Workspace · Shape · Passage and citation · Approval · Make two entities one · Two entities in the Graph are one thing