graph-schema

name: graph-schema description: Graph database schema design and data modeling expert. Use when designing, reviewing, or refactoring graph database schemas (Neo4j, Memgraph, Neptune, etc.). Triggers on graph modeling, node/relationship design, Cypher schema, property graph design, knowledge graph modeling, or when translating a domain into a graph structure. Focuses primarily on data modeling correctness — understanding the user's goal and translating it into the right graph structure — with performance as a secondary concern.

dot-skills Graph Database Schema Design Best Practices

Comprehensive graph database data modeling guide for property graphs (Neo4j, Memgraph, Amazon Neptune, etc.). Contains 46 rules across 8 categories, prioritized by modeling impact from critical (entity classification, relationship design) to incremental (scale and evolution). Each rule includes detailed explanations, real-world Cypher examples comparing incorrect vs. correct models, and specific impact descriptions.

Philosophy: Data modeling correctness first, performance second. Always ask "what is the user trying to achieve?" before choosing structure.

When to Apply

Reference these guidelines when:

• Designing a new graph database schema from domain requirements
• Translating a relational schema to a graph model
• Deciding whether something should be a node, relationship, or property
• Reviewing an existing graph schema for modeling errors
• Refactoring a graph that produces awkward or slow queries
• Planning for schema evolution and data growth

Rule Categories by Priority

Quick Reference

1. Entity Classification (CRITICAL)

• entity-events - Model multi-participant events as first-class nodes
• entity-shared-values - Promote shared property values to nodes
• entity-specific-labels - Use specific labels over generic ones
• entity-multi-label - Qualify entities with multiple labels
• entity-identity-state - Separate identity from mutable state
• entity-reify-actions - Reify lifecycle actions into nodes
• entity-avoid-god-nodes - Avoid kitchen-sink entity nodes

2. Relationship Design (CRITICAL)

• rel-specific-types - Use specific relationship types over generic ones
• rel-meaningful-direction - Choose semantically meaningful direction
• rel-naming-conventions - Follow UPPER_SNAKE_CASE for relationship types
• rel-no-redundant-reverse - Don't create redundant reverse relationships
• rel-properties-scope - Put data on relationships only when it describes the connection
• rel-single-semantic - One relationship type per semantic meaning
• rel-typed-over-filtered - Prefer typed relationships over generic + property filter

3. Property Placement (HIGH)

• prop-no-foreign-keys - Don't embed foreign keys as properties
• prop-promote-to-node - Promote frequently-queried values to nodes
• prop-correct-data-types - Use appropriate data types for properties
• prop-no-arrays-for-connections - Don't use property arrays when you need relationships
• prop-relationship-vs-node-data - Know when data belongs on relationship vs. node

4. Query-Driven Refinement (HIGH)

• query-critical-traversals - Design for your most critical traversals first
• query-shortcut-relationships - Add shortcut relationships for frequent multi-hop queries
• query-denormalize-reads - Denormalize for read-heavy paths
• query-filter-by-rel-props - Use relationship properties to filter traversals
• query-test-before-deploy - Test model against real queries before deploying

5. Structural Patterns (HIGH)

• pattern-intermediary-nodes - Use intermediary nodes for multi-entity relationships
• pattern-hierarchy - Model hierarchies with category nodes and depth relationships
• pattern-linked-list - Use linked lists for ordered sequences
• pattern-timeline-tree - Apply timeline trees for temporal data
• pattern-fan-out - Fan-out pattern for event streams and activity feeds
• pattern-bipartite - Use bipartite structure for many-to-many with context

6. Anti-Patterns (MEDIUM)

• anti-join-table-nodes - Don't model relational join tables as nodes
• anti-generic-relationships - Don't use generic RELATED_TO or CONNECTED relationships
• anti-relational-porting - Don't port relational schemas directly to graph
• anti-over-modeling - Don't make everything a node
• anti-duplicate-data - Don't duplicate data instead of creating relationships
• anti-string-encoded-structure - Don't encode structured data as delimited strings

7. Constraints & Integrity (MEDIUM)

• constraint-unique-identifiers - Define uniqueness constraints on natural identifiers
• constraint-existence - Use existence constraints for required properties
• constraint-index-traversals - Create indexes on traversal entry point properties
• constraint-no-over-index - Don't over-index — each index has a write cost
• constraint-node-key - Use composite node keys for natural multi-part identifiers

8. Scale & Evolution (LOW-MEDIUM)

• scale-supernode-mitigation - Mitigate supernodes with fan-out or partitioning
• scale-temporal-versioning - Separate current state from historical state
• scale-schema-migration - Plan for label and relationship type evolution
• scale-batch-refactoring - Use APOC or batched queries for schema refactoring
• scale-dense-node-detection - Monitor and detect emerging supernodes

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files