Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 14 additions & 9 deletions src/explanation/entity-integrity.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.*
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion src/how-to/model-relationships.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -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."
]
},
{
Expand Down
4 changes: 2 additions & 2 deletions src/how-to/read-diagrams.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
},
{
Expand Down
Loading