diff --git a/src/explanation/entity-integrity.md b/src/explanation/entity-integrity.md index 2bb05b83..709715f6 100644 --- a/src/explanation/entity-integrity.md +++ b/src/explanation/entity-integrity.md @@ -239,7 +239,7 @@ this table?"* - Adding a dimension makes the grain **finer**: a part table that adds `blob_idx` (`Detection.Blob` below) has grain **(… × blob)** — one row per blob of a detection. -- A computed table's grain is the combination of dimensions at which its `make()` +- An autopopulated table's grain is the combination of dimensions at which its `make()` produces rows — its [`key_source`](../reference/specs/autopopulate.md). *A computation operates at its grain.* @@ -305,11 +305,12 @@ class SubjectProfile(dj.Manual): one profile per subject. In schema diagrams, such tables have **non-underlined names**. -### Computed tables never introduce dimensions +### Autopopulated tables introduce dimensions only through part tables -A `Computed` table's primary key is fully inherited from its dependencies. -New entity types are introduced by Manual or Lookup tables, not by -computation: +An autopopulated table — `Computed` or `Imported` — runs its `make()` once per +key in its [`key_source`](../reference/specs/autopopulate.md), so the master's +primary key is fully inherited from its dependencies. The master introduces no +dimension of its own: ```python @schema @@ -322,10 +323,8 @@ class SessionSummary(dj.Computed): """ ``` -### Part tables CAN introduce dimensions - -Unlike Computed master tables, part tables can introduce new dimensions -when a single computation produces multiple related results: +When one `make()` call produces several results that need their own identifier, +that new dimension goes in a **part table**: ```python @schema @@ -350,6 +349,12 @@ class Detection(dj.Computed): `Detection` inherits its dimensions; `Detection.Blob` introduces `blob_idx` to identify individual blobs within each detection. +> **Introducing a new dimension in an autopopulated table requires a part +> table.** + +The master row and its part rows are inserted together in one transaction, so +the new dimension is populated atomically with the computation that defines it. + ### Dimensions and attribute lineage Every foreign-key attribute traces back to the dimension where it was first diff --git a/src/how-to/model-relationships.ipynb b/src/how-to/model-relationships.ipynb index cdf01bfd..74e5c195 100644 --- a/src/how-to/model-relationships.ipynb +++ b/src/how-to/model-relationships.ipynb @@ -1657,7 +1657,7 @@ "source": [ "**Thick solid line** to a **red (Computed) table** that is **not underlined**.\n", "\n", - "Computed tables never introduce dimensions — their primary key is entirely inherited from dependencies." + "An autopopulated master introduces no dimension of its own — its primary key is entirely inherited from dependencies. A new dimension in an autopopulated table requires a part table." ] }, { diff --git a/src/how-to/read-diagrams.ipynb b/src/how-to/read-diagrams.ipynb index 2d5f2a2c..e7d4811b 100644 --- a/src/how-to/read-diagrams.ipynb +++ b/src/how-to/read-diagrams.ipynb @@ -499,8 +499,8 @@ "| Not underlined | Exists in the space defined by dimensions from referenced tables |\n", "\n", "**Key rules:**\n", - "- Computed tables **never** introduce dimensions (always non-underlined)\n", - "- Part tables **can** introduce dimensions (may be underlined)" + "- An autopopulated master (`Computed`, `Imported`) is always non-underlined — its primary key is fully inherited from its dependencies\n", + "- A part table **can** be underlined; a part table is the only way an autopopulated table introduces a new dimension" ] }, {