Skip to content

Master-part spec: state the dimension rule and link the diagram's grouping #299

Description

@dimitri-yatsenko

Summary

reference/specs/master-part.md specifies definition, integrity, insertion and deletion, but it says nothing about two things the rest of the documentation relies on:

  1. The dimension rule. An auto-populated master introduces new dimensions only through its parts. explanation/entity-integrity.md states it ("Autopopulated tables introduce dimensions only through part tables", from docs: a new dimension in an autopopulated table requires a part table #276): a Computed or Imported table's primary key comes entirely from its dependencies, and when one make() call produces several results that each need an identifier, that identifier goes in a part table. The spec's §3.3 "Computed Tables with Parts" shows the pattern but never says why it is required. It also doesn't say what goes wrong without it: a computation that yields zero items leaves no row, so the key is recomputed on every populate(). The master row is what records that the computation ran.
  2. How a master-part group is drawn. dj.Diagram encloses a master and its parts in an unlabeled shaded group and names parts without the master prefix inside it. A reader of this spec should be able to find that, or a link to it, from here.

Proposed changes

  • In §1 (Definition) or §3.3, a short subsection, "Parts carry new dimensions". It covers:
    • the rule;
    • the zero-items case;
    • when a part's key adds an attribute (a new dimension: underlined, thin edge from the master) and when it doesn't (one row per row of another table: a thick edge from that table, not underlined, like Spectrum with one row per Scan);
    • a link to explanation/entity-integrity.md.
  • A one-paragraph "In diagrams" note linking to the diagram spec's master-part grouping (Diagram spec: document the master-part entity cluster #298).

Related: #276 (the dimension rule in the explanation), #222 (master-part spec: depending on the master implies its parts).

Activity

  1. dimitri-yatsenko commented on Oct 9, 2026

    @dimitri-yatsenko
    MemberAuthor

    Related library issue: datajoint/datajoint-python#1576 (declaration accepts an auto-populated table that declares its own primary-key attributes, with no warning).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions