Lesson 12

Deleting things

What flecs does to everything that refers to an entity when you delete it, how cleanup policies change that, and why deletes can be bulk table operations.

Deleting an entity is more than deleting its row. Other entities may refer to it, as a parent (ChildOf), as the target of a relationship ((Likes, Alice)), or because it is a component or tag someone has. flecs cleans all of those up when the entity goes, following cleanup policies set on the relationship or component:

ChildOf is set up with (OnDeleteTarget, Delete), which is why deleting a parent deletes its children. You can give your own relationships the same behaviour: OwnedBy below dies with its owner.

Watch a delete ripple out

What happens:

• alice.destruct() finds every pair with Alice as the target.
  • (Likes, Alice) uses the default policy (Remove). Bob’s whole table loses the pair at once: all its rows are merged into [Position] in one operation, rather than moved one by one.
  • (OwnedBy, Alice) has Delete, so the whole [Position, (OwnedBy, Alice)] table is cleared: Cargo is deleted, with OnRemove fired for it.
  • The tables that only existed for Alice’s pairs are deleted.
• ship.destruct() deletes its children in one table-wide clear, because they all share [Position, (ChildOf, Ship)]. That’s one more reason a parent’s children live in their own table.

The bulk operations are worth knowing about. Deleting a parent with a thousand children costs one table clear plus one OnRemove batch per table, not a thousand separate deletes.