docs: interlink schema-design concepts; fix PK/entity-integrity examples#216
Conversation
Ties together the closely-related schema-design concepts (normalization, primary keys, foreign keys / modeling relationships, entity integrity) both conceptually and through mutual See-also links, and corrects two examples. Content fixes: - entity-integrity.md 'Too many key attributes': (subject_id, timestamp) is a *valid* per-subject measurement key; replace the mischaracterized example with genuine over-keying (a descriptive attribute in the key). Use core types. - design-primary-keys.md 'Keep Keys Small': add a genuinely-oversized example (varchar(200) where an int32 suffices) and drop the incorrect 'Max 65,535' comment (that is int16's range). Cross-linking (the family was barely interconnected; normalization had no See-also at all): - design-primary-keys <-> entity-integrity: mutual links; state that the primary key is how a table enforces entity integrity. - normalization: new See-also -> entity-integrity, design-primary-keys, model-relationships, relational-workflow-model. - entity-integrity See-also -> design-primary-keys, model-relationships. - relational-workflow-model See-also -> the schema-design how-tos.
dimitri-yatsenko
added
the
documentation
…ity link - Drop 'Use Fixed-Width for Joins' (a myth — for indexed joins, key type and size matter, not fixed vs variable width). - Drop 'Avoid Dates as Primary Keys' — a date is valid key material for a date-identified entity; add a note saying so. - Add 'Avoid Floating-Point Keys' — float/double equality is unreliable (rounding); use decimal or integers. - Drop 'Avoid Computed Values' — a deterministic, immutable computed key (content hash, derived UUID) is fine; immutability is already a stated principle. - entity-integrity.md: state that entity integrity is largely primary-key design and link the Design Primary Keys how-to (bidirectional with the how-to's link back).
- entity-integrity.md 'Foreign keys': lead with 'referential integrity is impossible without entity integrity — identify unique entities before defining relationships,' tying FK -> PK. - design-primary-keys.md 'Natural Keys': adopt the actionable test — a key is natural when it identifies the entity outside the database (printed, written, spoken).
Expand normalization.md beyond its workflow-only framing: the three normalization lenses and their convergence, a classical 1NF/2NF/3NF baseline with functional dependencies, the Entity Normalization Principle (attributes describe the entity directly/completely/non-optionally), the e-commerce Order example showing workflow normalization is stricter than 3NF, the UPDATE-as-design-smell test, and a tidy-data callout. Preserves the existing mouse/cage worked example and See-also. Closes #219.
MilagrosMarin
left a comment
MilagrosMarin
left a comment
There was a problem hiding this comment.
Thanks — the interlinking is a real improvement, and both content fixes are correct: the (subject_id, timestamp) example was misleading (that's a valid per-subject measurement key), and the # Max 65,535 sessions comment on int32 was wrong (that's int16's range). Verified all internal links resolve and CI (spelling + linkcheck) passes. New three-lens framing in normalization.md reads well.
Two small observations, not blockers:
-
design-primary-keys.mddrops "Use Fixed-Width for Joins" and "Avoid Computed Values" without a note in the PR body. Both deletions are defensible — the char-vs-varchar guidance is arguably dated (modern InnoDB handles VARCHAR joins fine), and "avoid computed values" would conflict with DJ 2.x's hash-addressed storage as a first-class concept. Just calling it out in case one of them was meant to survive in some form. -
The e-commerce example in
normalization.mdusesdj.ManualforPayment,Shipment,Delivery. Pedagogically these would more naturally bedj.Imported(payment processor / carrier API) or auto-populated by workflow events;dj.Manualglosses over the ingestion mechanism. Minor — the point being made (workflow > 3NF) still lands cleanly.
Approving.
2 participants
Interlinks the closely-related schema-design concepts — normalization, primary keys, foreign keys / modeling relationships, entity integrity — both conceptually and through mutual cross-references, and fixes two misleading examples. Independent of the v2.3.2 code work (no notebook re-execution); separate from #215.
Content fixes
explanation/entity-integrity.md— "Too many key attributes". The example declared(subject_id, timestamp)as "Wrong… destroys entity identity" — but that's a valid per-subject measurement key. Rewrote it to say so, and replaced the example with genuine over-keying (a descriptive attribute —technician— placed in the key). Switched to core types (int32).how-to/design-primary-keys.md— "Keep Keys Small". Added a genuinely-oversized example (varchar(200)where anint32suffices — the key is copied into every child table, index, and join) and dropped the incorrect# Max 65,535 sessionscomment on anint32field (65,535 isint16's range).Interlinking (the family was barely connected;
normalization.mdhad no See-also at all)design-primary-keys.md↔entity-integrity.md— mutual links; the how-to now states the primary key is how a table enforces entity integrity.normalization.md— new "See also" → entity-integrity, design-primary-keys, model-relationships, relational-workflow-model.entity-integrity.md"See also" → design-primary-keys, model-relationships.relational-workflow-model.md"See also" → the schema-design how-tos.Notes
model-relationships.ipynbis intentionally untouched here (it's owned by docs(diagram): renamed FKs as orange edges [blocked on v2.3.2 / dj-python#1508] #215); the one remaining backlink (model-relationships → normalization) can be added there or in a follow-up.