Read Schema Diagrams¶

DataJoint diagrams visualize schema structure as directed acyclic graphs (DAGs). This guide teaches you to:

• Interpret line styles and their semantic meaning
• Recognize dimensions (underlined vs non-underlined tables)
• Use diagram operations to explore large schemas
• Compare DataJoint notation to traditional ER diagrams

Quick Reference¶

Key principle: Solid lines mean the parent's identity becomes part of the child's identity. Dashed lines mean the child maintains independent identity.

Thick Solid Line: Extension (One-to-One)¶

The foreign key is the entire primary key. The child extends the parent.

Equivalent ER Diagram:

DataJoint vs ER: The thick solid line immediately shows this is one-to-one. In ER notation, you must read the crow's foot symbols (||--o|).

Note: CustomerPreferences is not underlined — it exists in the Customer dimension space.

Thin Solid Line: Containment (One-to-Many)¶

The foreign key is part of the primary key, with additional fields.

Equivalent ER Diagram:

DataJoint vs ER: The thin solid line shows containment — accounts belong to customers. In ER, you see ||--o{ (one-to-many).

Note: Account is underlined — it introduces the Account dimension.

Dashed Line: Reference (One-to-Many)¶

The foreign key is a secondary attribute (below the --- line).

Equivalent ER Diagram:

DataJoint vs ER: Both show one-to-many, but DataJoint's dashed line tells you immediately that Employee has independent identity. In ER, you must examine whether the FK is part of the PK.

Note: Both tables are underlined — each introduces its own dimension.

Dimensions and Underlined Names¶

A dimension is a new entity type introduced by a table that defines new primary key attributes. Each underlined table introduces exactly one dimension—even if it has multiple new PK attributes, together they identify one new entity type.

Key rules:

• Computed tables never introduce dimensions (always non-underlined)
• Part tables can introduce dimensions (may be underlined)

In this diagram:

• Subject is underlined — introduces the Subject dimension
• Session is underlined — introduces the Session dimension (within each Subject)
• SessionQC is not underlined — exists in the Session dimension space, adds no new dimension

Why this matters: Dimensions determine attribute lineage. Primary key attributes trace back to the dimension where they originated, enabling semantic matching for safe joins.

Many-to-Many: Converging Lines¶

Many-to-many relationships appear as tables with multiple solid lines converging.

Equivalent ER Diagram:

DataJoint vs ER: Both show the association table pattern. DataJoint's converging solid lines immediately indicate the composite primary key.

Note: Enrollment is not underlined — it exists in the space defined by Student × Course dimensions.

Orange Dots: Renamed Foreign Keys¶

When referencing the same table multiple times, use .proj() to rename. Orange dots indicate renamed FKs.

The orange dots between Person and Marriage indicate that projections renamed the foreign key attributes (spouse1 and spouse2 both reference person_id).

Tip: In Jupyter, hover over orange dots to see the projection expression.

Diagram Operations¶

Filter and combine diagrams to explore large schemas:

Operation Reference:

Finding paths: Use intersection to find connection paths:

(dj.Diagram(upstream) + 100) * (dj.Diagram(downstream) - 100)

Layout Direction¶

New in DataJoint 2.1

Control the flow direction of diagrams via configuration:

Mermaid Output¶

New in DataJoint 2.1

Generate Mermaid syntax for embedding diagrams in Markdown documentation, GitHub, or web pages:

Copy this output into any Mermaid-compatible viewer (GitHub Markdown, MkDocs with mermaid plugin, https://mermaid.live) to render the diagram.

Saving to file:

dj.Diagram(schema).save("pipeline.mmd")  # .mmd or .mermaid extension

Multi-Schema Pipelines¶

Real-world pipelines often span multiple schemas (modules).

New in DataJoint 2.1: Tables are automatically grouped into visual clusters by schema, with the Python module name shown as the group label.

Tables are grouped by their database schema automatically. The group label shows the Python module name when available (following the DataJoint convention of one module per schema).

Multi-schema diagrams are useful for:

• Visualizing pipelines spanning multiple schemas
• Understanding which tables belong to which module
• Documentation for multi-module architectures

Collapsing Schemas¶

New in DataJoint 2.1

For high-level pipeline views, collapse entire schemas into single nodes using .collapse(). This is useful for showing relationships between modules without the detail of individual tables.

The collapsed node shows the module name and table count. Edges from the expanded schema connect to the collapsed node.

"Expanded wins" rule: If a table appears in both a collapsed and non-collapsed diagram, it stays expanded. This applies even when expanding a single table from a collapsed schema:

Preserving directionality: Collapsing middle layers of a pipeline preserves the DAG structure. The collapsed node sits between expanded tables, maintaining edge directions:

Extended Example: Multi-Module Pipeline¶

Here's a realistic example with three modules that have cross-schema dependencies:

demo_modules/acquisition.py - Core data acquisition:

@schema
class Lab(dj.Manual):
    definition = """lab : varchar(32) ..."""

@schema
class Subject(dj.Manual):
    definition = """subject_id : varchar(16) --- -> Lab ..."""

@schema
class Session(dj.Manual):
    definition = """-> Subject  session_date : date ..."""

demo_modules/processing.py - Data processing (references acquisition):

@schema
class ProcessingParams(dj.Lookup):
    definition = """params_id : int16 ..."""

@schema
class ProcessedSession(dj.Computed):
    definition = """-> acquisition.Session  -> ProcessingParams ..."""

@schema
class EventDetection(dj.Computed):
    definition = """-> ProcessedSession  event_id : int32 ..."""

demo_modules/analysis.py - Analysis (references both modules):

@schema
class AnalysisParams(dj.Lookup):
    definition = """analysis_id : int16 ..."""

@schema
class SubjectAnalysis(dj.Computed):
    definition = """-> acquisition.Subject  -> AnalysisParams ..."""

@schema
class CrossSessionAnalysis(dj.Computed):
    definition = """-> acquisition.Subject  -> processing.ProcessingParams ..."""

The full diagram shows all three modules with cross-schema references:

• acquisition provides core tables (Lab, Subject, Session)
• processing references Session from acquisition
• analysis references Subject from acquisition AND ProcessingParams from processing

Now let's see collapse in action:

Key observations:

1. Collapsed nodes show table count — e.g., "processing (3 tables)"
2. Cross-schema edges preserved — Dependencies between modules are shown as edges between collapsed nodes
3. "Expanded wins" — If you explicitly include a table (like Subject), it stays expanded even if a collapsed schema references it
4. Schema-level DAG — Collapsing all schemas reveals the high-level module dependency graph, useful for understanding pipeline architecture

What Diagrams Don't Show¶

Diagrams do NOT show these FK modifiers:

A dashed line could be any of:

• Required one-to-many (default)
• Optional one-to-many ([nullable])
• Required one-to-one ([unique])
• Optional one-to-one ([nullable, unique])

Always check the table definition to see modifiers.

DataJoint vs Traditional ER Notation¶

Why DataJoint differs:

1. DAG structure — No cycles means schemas read as workflows (top-to-bottom)
2. Line semantics — Immediately reveals relationship type
3. Executable — Diagram is generated from schema, cannot drift out of sync

Summary¶

Related¶

• Diagram Specification
• Entity Integrity: Dimensions
• Semantic Matching
• Schema Design Tutorial