Skip to content

docs: a new dimension in an autopopulated table requires a part table - #276

Merged
dimitri-yatsenko merged 1 commit into
mainfrom
docs/autopopulated-dimensions-via-parts
Sep 10, 2026
Merged

docs: a new dimension in an autopopulated table requires a part table#276
dimitri-yatsenko merged 1 commit into
mainfrom
docs/autopopulated-dimensions-via-parts

Conversation

@dimitri-yatsenko

Copy link
Copy Markdown
Member

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 dimensions

Two problems:

  1. Scope. The rule was stated for Computed, but it holds for any autopopulated table — Imported too. The reason is the key_source, which both tiers share, not anything specific to Computed.
  2. Framing. A prohibition followed by its exception buries the thing a designer actually needs to know: where the new dimension goes.

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:

An autopopulated table — Computed or Imported — runs its make() once per key in its key_source, so the master's primary key is fully inherited from its dependencies. The master introduces no dimension of its own.

When one make() call produces several results that need their own identifier, that new dimension goes in a part table.

ending on the rule as a callout:

Introducing a new dimension in an autopopulated table requires a part table.

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:

file was now
how-to/read-diagrams.ipynb "Computed tables never introduce dimensions (always non-underlined)" / "Part tables can introduce dimensions" an autopopulated master is always non-underlined; a part table is the only way an autopopulated table introduces a new dimension
how-to/model-relationships.ipynb "Computed tables never introduce dimensions — their primary key is entirely inherited" same, plus "A new dimension in an autopopulated table requires a part table"

Also generalized the grain bullet from "a computed table's grain" to "an autopopulated table's grain", for the same reason.

src/llms-full.txt also 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 --strict passes.
  • Both guards clean: 142 pages with no broken internal links, no swallowed lists.
  • The renamed section has no inbound anchor links anywhere in src/ (checked before renaming), and the new #autopopulated-tables-introduce-dimensions-only-through-part-tables id renders; the two old ids are gone.
  • The rule callout renders as a real <blockquote>.

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
@dimitri-yatsenko dimitri-yatsenko added the documentation Improvements or additions to documentation label Sep 10, 2026
@dimitri-yatsenko
dimitri-yatsenko merged commit 1f27540 into main Sep 10, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants