Refresh sections on relationships and diagrams. #12
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Update chapter title for consistency with "Schemas" chapter naming convention, and update references in 010-schema.ipynb and 082-indexes.ipynb.
Move Primary Keys chapter (018) before Lookup Tables (020) since primary keys are a fundamental concept used in lookup table examples. Update all cross-references to the renamed files.
- Rename title from "Primary Key" to "Primary Keys" for consistency - Add YAML frontmatter and Learning Objectives - Streamline content: 818 lines → ~320 lines - Remove redundant UUID implementation details (defer to UUID chapter) - Remove repetitive practical examples - Add decision framework flowchart for key type selection - Add clear "Next Steps" connecting to subsequent chapters - Improve didactic presentation with tables and structured sections
…les-chapter-Clu2N Rename Create Tables, reorder Primary Keys.
- Clarify that natural keys can be simple or composite (not mutually exclusive) - Remove auto_increment as recommended pattern (anti-pattern in DataJoint) - Explain that explicit surrogate keys prevent entity integrity violations - Correct join semantics to describe semantic matching (same name + same lineage) - Update decision framework to reflect corrected concepts - Add references to Relationships chapter for composite key patterns
- Introduce schema dimensions as key concept for understanding semantic matching - Explain that tables introducing new primary key attributes create new dimensions - Document diagram notation: underlined names indicate dimension-defining tables - Update semantic matching explanation to use schema dimensions terminology - Connect dimensions to how joins and restrictions work in DataJoint - Add schema dimensions to learning objectives and summary
- Auto-populated tables (Computed, Imported) cannot introduce new dimensions - Their primary key must be fully determined by foreign keys to parent tables - Part tables CAN introduce new dimensions (e.g., cell_id for detected cells) - Add examples showing ProcessedScan (no new dimension) and CellDetection.Cell (new dimension) - Explain rationale: reproducibility, well-defined key source, traceable computations
…ocs-00Ea8 Fix primary key classification in documentation, introduce "schema dimensions"
Master-part chapter: - Add point about part tables introducing new schema dimensions - Explain auto-populated masters cannot add dimensions, but parts can - Add "Schema Dimensions in Computed Tables" subsection - Update blob detection example to highlight blob_id as new dimension - Add schema dimensions to summary principles - Cross-reference Primary Keys chapter Populate chapter: - Add "Schema Dimensions and the Key Source" section - Explain why auto-populated tables cannot introduce dimensions - Show how this constraint makes key source well-defined - Explain part tables as solution for multi-output computations - Update blob detection case study to mention dimensions - Add Primary Keys to seealso references
…tegrity Natural vs Surrogate keys: - Natural keys: used outside the database to refer to entities in the real world - Key distinction is real-world usage, not origin (even system-generated IDs become natural if used externally) - Example: colony-generated animal IDs become natural keys when printed on ear tags - Surrogate keys: used only inside the database, not exposed to users - Example: internal post IDs on social media (users search by content, not ID) Partial entity integrity: - Sometimes only one direction of integrity is needed - Record→Entity: each record maps to one entity (but entity may have multiple records) - Entity→Record: each entity has a record (but records may be shared) - Example: social media preventing account sharing but allowing multiple accounts Entity integrity without natural keys: - Still possible but requires multi-step identification process - Database ensures uniqueness; external processes ensure entity-record matching - Comprehensive process design required outside the database
…ocs-00Ea8 Describe "schema dimensions"
Add four sections from earlier version to enhance the chapter: - Opening hook with real-world impact examples (HR/dentist scenarios) - Historical SSN example with critical thinking questions and links - Real-world identification standards callout (VIN, RFID, aircraft) - University student database example alongside lab mouse example
- Move Default Values chapter after Primary Key (017 → 019) - Expand "Explicitly Defined Keys" admonition to comprehensive explanation of why DataJoint prohibits default values in primary key attributes - Add cross-reference warning in Default Values chapter - Simplify duplicate warning in Decision Framework section - Document client-side surrogate key alternatives (UUID, ULID, NANOID)
…ey-narrative-5v66x Restore narrative to Primary Key chapter
Use 5 backticks for the outer admonition directive to prevent conflict with the nested Python code block inside it. This fixes the "Composite Keys in Hierarchical Relationships" section being incorrectly rendered as code.
- Reword section header for better narrative flow - Add cross-reference to Special Topics UUID chapter - Mention UUID variants (UUID1, UUID4, UUID5), ULIDs, and NANOIDs - Clarify that these methods satisfy DataJoint's explicit key requirement
…s-markdown-S8Q25 Fix markdown rendering in Composite Keys section
The flowchart decision framework was too prescriptive for the nuanced decisions involved in choosing primary keys. The table summarizing recommended approaches by scenario is retained as it provides useful guidance without implying a mechanical decision process.
…ey-framework-c9OHB Improve primary key selection decision framework
Add MyST tab-set syntax to display DataJoint Python code alongside equivalent SQL statements. This allows readers to toggle between the two syntaxes and see the relationship between them. Tables converted to tabs: - Mouse table (ear_tag example) - Student table - Mouse table (animal_id/natural key) - InternalRecord (surrogate key) - Session with insert example (inside admonition) - Subject/Session (composite keys) - Subject/Session/Scan hierarchy (schema dimensions) - ProcessedScan (auto-populated tables) - CellDetection with Cell part table - Query examples (restriction and join)
…key-tabs-AKwyr Organize Primary Key chapter with tabs
Restructure MyST tab-sets to properly nest code blocks with language identifiers (```python and ```sql). This requires using more backticks for outer directives to allow proper nesting: - Tab-sets use 5 backticks - Tab-items use 4 backticks - Code blocks use 3 backticks with language specifier Also updated the admonition containing tabs to use 6 backticks for proper nesting of the inner tab-set.
…key-tabs-AKwyr Fix syntax highlighting in tab-set code blocks
Remove authors and date fields from YAML frontmatter across 8 chapter files, keeping only the title metadata. This simplifies the chapter headers by removing attribution that is tracked elsewhere.
- Add YAML frontmatter with title - Fix typo: "DataJoitn" → "DataJoint" - Fix broken link to Primary Keys chapter (add ../30-design/ path) - Add detailed UUID type characteristics (UUID1, UUID4, UUID3/UUID5) - Add "When to Use UUIDs" section with clear criteria - Add "Choosing the Right UUID Type" decision table - Improve cross-references between UUID and Primary Keys chapters - Add summary section with next steps - Streamline ULID and NANOID sections
- 018-primary-key.md: Wrap SQL COMMENT and FOREIGN KEY statements - 020-lookup-tables.ipynb: Format periodic table elements one per line - 044-generations.ipynb: Shorten generation characteristics text - 050-languages.ipynb: Format language and CEFR contents lists - 060-management.ipynb: Wrap employee data dictionary literals - 083-attach.ipynb: Wrap long description strings and URLs - 084-filepath.ipynb: Wrap URL strings and path concatenations - SPECS_2_0.md: Wrap student insert examples and query expressions
…tadata-BjOhA Remove dates and authors from chapters
… chapter - Convert Foreign Keys, Relationships, and Diagrams from .ipynb to .md format - Add learning objectives, proper admonition boxes, and tab-set for DataJoint/SQL examples - Introduce foreign key modifiers (nullable and unique) with complete syntax and semantics - Document that primary key foreign keys cannot be nullable - Clarify that diagram notation does NOT reflect nullable/unique modifiers - Add comprehensive relationship patterns: one-to-one, one-to-many, many-to-many - Include hierarchies, sequences, parameterization, and directed graph patterns - Update all cross-references from .ipynb to .md throughout the book
…-keys-IzuUB Harmonize foreign keys and relationships chapters
…-keys-IzuUB Fix nested code block syntax highlighting in Foreign Keys chapter
Add missing parent table definitions to SQL examples: - Pattern 2: Add Customer table - One-to-One Pattern 1: Add Customer table - One-to-One Pattern 2: Add Employee table - Many-to-Many: Add Student and Course tables - Parameterization: Add Image and EnhanceMethod tables - Directed Graphs: Add Neuron table - Design Puzzle: Add State table
…-keys-IzuUB Complete SQL examples in Relationships chapter to match DataJoint code
Add missing parent table definitions to SQL examples: - Thick Solid Line: Add customer table - Thin Solid Line: Add customer table - Dashed Line: Add department table - Association Tables: Add student and course tables - Renamed Foreign Keys: Add neuron table
- Convert 050-relationships.md to 050-relationships.ipynb with executable diagram cells while preserving MyST tab-sets in markdown cells - Convert 060-diagrams.md to 060-diagrams.ipynb with executable diagram cells while preserving MyST tab-sets in markdown cells - Add dj.Diagram() calls to generate visual diagrams for each example - Update all cross-references from .md to .ipynb in related files
…-keys-IzuUB Add diagrams into Relationships
Document the intersection operator for DataJoint Diagrams that shows only common nodes between two diagrams. This is particularly useful for finding connection paths between tables in large schemas by expanding one table downstream and another upstream, then intersecting them.
…section-OV8Wi Add intersection operator for diagram operations
Move Diagramming chapter to follow immediately after Foreign Keys, placing it before Relationships. This pedagogical order allows readers to learn visual notation before exploring relationship patterns. - Rename 060-diagrams.ipynb to 040-diagrams.ipynb - Update cross-references in all three chapters - Harmonize narrative flow between chapters
…m-sections-YwHn8 Reorganize diagramming and relationships sections
Add a new section comparing enums and lookup tables for specifying valid values, using the grades example. Includes code examples, a comparison table, and guidance on when to use each approach.
Mention that lookup tables can be queried to dynamically populate dropdown menus in graphical interfaces and dashboards, avoiding hardcoded values in the application.
…-discussion-B1O9n Add lookup tables discussion to Relationships section
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.