Skip to content

Add a referential-integrity / foreign-keys explanation page #218

Description

@dimitri-yatsenko

The book has a dedicated Foreign Keys chapter (30-design/030-foreign-keys.md); the docs split FK material between explanation/entity-integrity.md and the how-to/model-relationships.ipynb how-to, with no dedicated referential-integrity explanation page — an asymmetry with the book's entity-key / foreign-key structure.

Concepts currently missing:

  • A foreign key is a runtime logical constraint, not a physical pointer — an insert triggers a search of the parent to verify a matching key exists; it is not a disk link. (The HDF5-pointer contrast is worth keeping.)
  • The five effects of a foreign key — schema embedding, insert restriction on the child, delete restriction on the parent (cascade), update restriction on keys, and automatic index creation. They're never enumerated together, and the auto-index effect is entirely absent from the docs.

Proposal: add explanation/referential-integrity.md covering both, plus the "referential integrity is impossible without entity integrity" dependency (now added to entity-integrity.md in PR #216 — link it).

From an internal datajoint-book → docs coverage review (priority P2).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions