docs: a new dimension in an autopopulated table requires a part table - #276
Merged
Merged
Conversation
The dimensions discussion said "Computed tables never introduce dimensions" and then, in a separate section, that part tables can. Two problems: the rule was scoped to Computed when it holds for any autopopulated table (Imported too), and stating it as a prohibition buries the thing a designer actually needs, which is where the new dimension goes. Merge the two sections and state it positively: an autopopulated master inherits its whole primary key and introduces no dimension of its own, so a new dimension goes in a part table. Both code examples are kept -- the master case and the part case now read as one argument. Note that master and part rows insert in one transaction, so the new dimension is populated atomically with the computation that defines it. Generalize the grain bullet from "a computed table's grain" to "an autopopulated table's grain", and carry the same reframing into the two how-to pages that repeated the old claim: - how-to/read-diagrams.ipynb: the underlining "key rules" - how-to/model-relationships.ipynb: the 1:1-extension note
MilagrosMarin
approved these changes
Sep 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Per feedback on https://docs.datajoint.com/explanation/entity-integrity/: rather than saying computed tables cannot add dimensions, say that autopopulated tables can add them only through a part table.
What was wrong
Two adjacent sections made the point in the negative, then walked it back:
### Computed tables never introduce dimensions### Part tables CAN introduce dimensionsTwo problems:
Computed, but it holds for any autopopulated table —Importedtoo. The reason is thekey_source, which both tiers share, not anything specific toComputed.What it says now
One section,
### Autopopulated tables introduce dimensions only through part tables, keeping both code examples so the master case and the part case read as a single argument:ending on the rule as a callout:
I also added a sentence on why the part table is the right home: master and part rows insert in one transaction, so the new dimension is populated atomically with the computation that defines it.
Consistency pass
The old claim was repeated in two how-to pages, which would have contradicted the explanation page:
how-to/read-diagrams.ipynbhow-to/model-relationships.ipynbAlso generalized the grain bullet from "a computed table's grain" to "an autopopulated table's grain", for the same reason.
src/llms-full.txtalso carries the old wording in three places, but it is auto-generated and untracked, so it picks this up on the next build.Verification
mkdocs build --strictpasses.src/(checked before renaming), and the new#autopopulated-tables-introduce-dimensions-only-through-part-tablesid renders; the two old ids are gone.<blockquote>.