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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions