> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Relationship

> A relationship joins two entities in one direction under a type that a Shape declares, and you create or change it only through a workspace.

Concept · graph

> **Use when**
>
> You connect two entities, read what an entity connects to, change a relationship, or move connections from one entity to another.

> **Looking for something else?**
>
> A change to one entity's own properties (card [Entity](https://docs.pnbr.io/concepts/entity.md)). Several changes reviewed together (card [Workspace](https://docs.pnbr.io/concepts/workspace.md)). Two entities that are one thing (recipe [Make two entities one](https://docs.pnbr.io/guides/resolve-duplicates.md)).

## 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](https://docs.pnbr.io/concepts/entity.md).
* A reviewed set of new and changed entities and relationships: use card
  workspace.
* Two entities that are one thing: use recipe [resolve-duplicates](https://docs.pnbr.io/guides/resolve-duplicates.md).

## 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](https://docs.pnbr.io/concepts/workspace.md#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](https://docs.pnbr.io/concepts/entity.md#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](https://docs.pnbr.io/concepts/passage.md#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](https://docs.pnbr.io/concepts/relationship.md#rule-relationship-3), and problem
  [same-name-two-entities](https://docs.pnbr.io/troubleshooting/same-name-two-entities.md).
* Validate reports `relationship_declaration_missing`: rule [relationship.1](https://docs.pnbr.io/concepts/relationship.md#rule-relationship-1).
* A stage call fails with `relationship_ambiguous`: several Shapes declare the type for these entities. Name the Shape in the [shape](https://docs.pnbr.io/concepts/shape.md) 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](https://docs.pnbr.io/concepts/relationship.md#rule-relationship-6).
* Two entities are one thing and each holds some connections: problem
  [merge-duplicates](https://docs.pnbr.io/troubleshooting/merge-duplicates.md).

## Doors

| Door | Call |
| - | - |
| CLI | `penumbra graph edges`, `penumbra graph get`, `penumbra graph traverse`, `penumbra graph workspace capture`, `penumbra graph workspace hydrate`, `penumbra graph workspace modify` |
| MCP (default) | `read` with the reference `entity:<id>` lists the first 50 connections with their ids. `execute` stages and checks them out, as the Program row says. |
| MCP (full catalog) | `search_graph` with `resource_kinds`, `traverse_graph`, `capture`, `workspace_hydrate`, `workspace_modify` |
| Program | In `execute`: `entity.related(relationship, neighborType, {direction, limit, cursor})` reads connections and returns the relationship id as `edge.id`. `penumbra.domain.stage({workspace, relationships})` stages. `workspace.hydrate({edges, intent})` checks out. |
| SDK | `ProjectGraph.listEdges`, `ProjectGraph.getEdge`, `GraphWorkspace.capture`, `GraphWorkspace.hydrate` |

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](https://docs.pnbr.io/api/http-graph-nodes-list.md)
* [Get graph node](https://docs.pnbr.io/api/http-graph-nodes-get.md)
* [Get node history](https://docs.pnbr.io/api/http-graph-nodes-history.md)
* [List graph edges](https://docs.pnbr.io/api/http-graph-edges-list.md)
* [Get graph edge](https://docs.pnbr.io/api/http-graph-edges-get.md)
* [Get edge history](https://docs.pnbr.io/api/http-graph-edges-history.md)
* [Count graph records](https://docs.pnbr.io/api/http-graph-counts.md)
* [Traverse graph](https://docs.pnbr.io/api/http-graph-traverse.md)
* [List graph commits](https://docs.pnbr.io/api/http-graph-commits-list.md)
* [Get graph commit](https://docs.pnbr.io/api/http-graph-commits-get.md)

## Keep going

[Entity](https://docs.pnbr.io/concepts/entity.md) · [Workspace](https://docs.pnbr.io/concepts/workspace.md) · [Shape](https://docs.pnbr.io/concepts/shape.md) · [Passage and citation](https://docs.pnbr.io/concepts/passage.md) · [Approval](https://docs.pnbr.io/concepts/approval.md) · [Make two entities one](https://docs.pnbr.io/guides/resolve-duplicates.md) · [Two entities in the Graph are one thing](https://docs.pnbr.io/troubleshooting/merge-duplicates.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.