Neo4j Modeling Skill

When to Use

• Designing graph model from scratch (domain → nodes, rels, props)
• Reviewing existing model for anti-patterns
• Deciding node vs property vs relationship vs label
• Migrating relational or document schema to graph
• Designing intermediate nodes for n-ary or complex relationships
• Detecting and mitigating supernode / high-fanout problems
• Choosing and creating constraints + indexes for a model

When NOT to Use

• Writing or optimizing Cypher → neo4j-cypher-skill
• Spring Data Neo4j (@Node, @Relationship) → neo4j-spring-data-skill
• GraphQL type definitions → neo4j-graphql-skill
• Importing data (LOAD CSV, APOC import) → neo4j-import-skill

Inspect Before Designing

On existing database, run first — never propose changes without current state:

CALL db.schema.visualization() YIELD nodes, relationships RETURN nodes, relationships;
SHOW CONSTRAINTS YIELD name, type, labelsOrTypes, properties RETURN name, type, labelsOrTypes, properties;
SHOW INDEXES YIELD name, type, labelsOrTypes, state WHERE state = 'ONLINE' RETURN name, type, labelsOrTypes;

If APOC available:

CALL apoc.meta.schema() YIELD value RETURN value;

MCP tool map:

Defaults — Apply to Every Model

1. Use-case first — list 5+ queries the model must answer before designing
2. Nodes = entities (nouns) with identity; rels = connections (verbs) with direction
3. Labels PascalCase; rel types SCREAMING_SNAKE_CASE; properties camelCase
4. Every node type used in MERGE has a uniqueness constraint on its key property
5. Add property type constraints (REQUIRE n.prop IS :: STRING) where the type is known — helps the query planner and catches bad writes early
6. No generic labels (:Entity, :Node, :Thing); no generic rel types (:RELATED_TO, :HAS)
7. Security labels (used for row-level access control) should start with a common prefix (e.g. Sec) so application code can reliably filter them out of the domain schema
8. Rel direction encodes semantic meaning — not arbitrary
9. Inspect schema before proposing any change on an existing database
10. All constraint/index DDL uses IF NOT EXISTS — safe to rerun
11. On Neo4j 2026.06+ (Enterprise/Aura, GA): declare the full model in one block with ALTER CURRENT GRAPH TYPE SET { … }, extend it with ALTER CURRENT GRAPH TYPE ADD { … }, instead of individual CREATE CONSTRAINT statements — see neo4j-cypher-skill/references/graph-type.md. On 2026.02–2026.05 the same syntax is preview.

Key Patterns

Node vs Relationship vs Property — Decision Table

Property vs Label — Decision Table

Rule: adding a label is cheap; scanning all :Label nodes is fast. Never model high-cardinality values as labels.

Intermediate Node Pattern

Use when a relationship needs its own properties, connects >2 entities, or is independently queryable.

Before (relationship with property — limited):

(Person)-[:ACTED_IN {role: "Neo"}]->(Movie)
// Cannot query roles independent of movies

After (intermediate node — queryable, extensible):

(Person)-[:PLAYED]->(Role {name: "Neo"})-[:IN]->(Movie)
// MATCH (r:Role) WHERE r.name STARTS WITH 'Neo' RETURN r

Employment overlap example:

// Find colleagues who overlapped at same company
MATCH (p1:Person)-[:WORKED_AT]->(e1:Employment)-[:AT]->(c:Company)<-[:AT]-(e2:Employment)<-[:WORKED_AT]-(p2:Person)
WHERE p1 <> p2
  AND e1.startDate <= e2.endDate AND e2.startDate <= e1.endDate
RETURN p1.name, p2.name, c.name

Promote relationship to intermediate node when:

• Relationship has >2 properties
• Relationship is the subject of another query
• Multiple entities share the same connection context
• You need to connect >2 entities in one fact

Relational → Graph Migration Table

Supernode Detection and Mitigation

Detect:

// Find top-10 highest-degree nodes
MATCH (n)
RETURN labels(n) AS labels, elementId(n) AS id, count{ (n)--() } AS degree
ORDER BY degree DESC LIMIT 10

Node with degree >> median for its label = supernode candidate. Any node with >100K relationships will degrade traversal queries that pass through it.

Causes:

• Domain supernodes: airports, celebrities, popular hashtags — unavoidable
• Modeling supernodes: gender, country, status modeled as nodes with millions of edges — avoidable

Mitigation strategies (in priority order):

Bucket pattern (time-series / high-volume):

// Instead of: (:User)-[:VIEWED]->(:Page) (millions of rels per user)
// Bucket by hour:
(u:User)-[:VIEWED_IN]->(b:ViewBucket {userId: u.id, hour: '2025-04-28T14'})-[:VIEWED]->(p:Page)

// Query last hour's views without traversing full history:
MATCH (u:User {id: $uid})-[:VIEWED_IN]->(b:ViewBucket {hour: $hour})-[:VIEWED]->(p)
RETURN p.url

Naming Conventions