Skip to main content
Troubleshooting · graph

Use when

A search, a read or a validate shows two entities with the same name, and you must decide whether they are the same thing.

Looking for something else?

Two entities you already know are one thing (recipe Make two entities one). A workspace that holds an item the Graph already has (problem An extraction found an entity the Graph already has).

​
Signs

  • penumbra graph search "<name>" returns two entities with the same name and type, and different ids.
  • penumbra graph workspace validate prints the warning duplicate_name.
  • A relationship that names its end by name is refused with node_ambiguous, and the reply lists candidates.
  • A person says “I have two of these”.

​
Why it happens

A name is a label. The id is the identity. Penumbra does not require names to be unique. It does not compare the name of an entity you stage by hand with the names already in the Graph. An extraction does compare its items (card rule extraction.9). Two entities can share a name because they are two things, such as two people called Ada. They can also share a name because the same thing was saved twice. Only a comparison of the entities tells you which.

​
What Penumbra does

By itself:
  • Accepts two entities with one name, also of one type.
  • Warns duplicate_name at validate when one workspace stages two entities of the same type with the same name, ignoring case and extra spaces.
  • Refuses a relationship end given as a name that matches several entities, with node_ambiguous.
You must:
  • Compare the two entities and decide whether they are one thing.
  • Name every entity by its id, not by its name.
Not handled:
  • No warning when an entity that you stage by hand has the same name as an entity already in the Graph.
  • No warning or flag on two entities that are already in the Graph with one name.

​
Do

  1. Read both entities. Run penumbra context entity <id> --json for each id. Compare the properties, the source Files and the relationships.
  2. If the entities differ, leave them. In every relationship you stage, pass ids, not names (card rule relationship.3).
  3. If they are one thing, follow recipe resolve-duplicates.
  4. If you cannot tell, ask the person. Give both ids, what is the same, and what differs. Do not delete either entity first.
  5. If the warning came from your own staged entities, remove the extra one with penumbra graph workspace modify before you submit.

​
Don’t

  • Don’t treat the warning duplicate_name as a block. A submit goes ahead with the warning (card rule workspace.3), and both entities are saved.
  • Don’t pick an entity by its name when a duplicate may exist. The call fails with node_ambiguous.
  • Don’t delete one of the two because the names match. A delete removes its relationships too (card rule entity.3).

​
Check

  • For each pair, you can say whether it is one thing or two, and why.
  • Every relationship you staged names its ends by id.
  • For a pair that is one thing, the check of recipe resolve-duplicates passes.
Card rule relationship.3. Card rule workspace.3. Recipe resolve-duplicates. Problem merge-duplicates. Problem extraction-duplicates-existing-entity.

​
Keep going

Entity · Relationship · Workspace · Make two entities one · Two entities in the Graph are one thing · An extraction found an entity the Graph already has