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:

Operation	Tool
Inspect schema	`get-schema`
`SHOW CONSTRAINTS`, `SHOW INDEXES`	`read-cypher`
`CREATE CONSTRAINT ... IF NOT EXISTS`	`write-cypher` (show + confirm first)

Defaults — Apply to Every Model

Use-case first — list 5+ queries the model must answer before designing
Nodes = entities (nouns) with identity; rels = connections (verbs) with direction
Labels PascalCase; rel types SCREAMING_SNAKE_CASE; properties camelCase
Every node type used in MERGE has a uniqueness constraint on its key property
Add property type constraints (REQUIRE n.prop IS :: STRING) where type known — catches bad writes early. Enterprise only; Community: use uniqueness constraints, validate types in app
No generic labels (:Entity, :Node, :Thing); no generic rel types (:RELATED_TO, :HAS)
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
Rel direction encodes semantic meaning — not arbitrary
Inspect schema before proposing any change on an existing database
All constraint/index DDL uses IF NOT EXISTS — safe to rerun
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 — details in neo4j-cypher-skill (GRAPH TYPE reference). Not on Community (ALTER CURRENT GRAPH TYPE SET → "not supported in community edition"): use individual constraints. On 2026.02–2026.05 syntax is preview.

Key Patterns

Node vs Relationship vs Property — Decision Table

Question	Answer	Model as
Is it a thing with identity, queried as entry point?	Yes	Node
Is it a connection between two things with direction?	Yes	Relationship
Does the connection have its own properties or multiple targets?	Yes	Intermediate node
Is it a scalar always returned with its parent, never filtered alone?	Yes	Property on parent
Is it a category used for type-based filtering or path traversal?	Yes	Label (not a property)
Does the same attribute value repeat across many nodes (low cardinality)?	Yes	Label, not a property node
Is it a fact connecting >2 entities?	Yes	Intermediate node

Property vs Label — Decision Table

Use label when	Use property when
Values are few, fixed, used as traversal filters (`WHERE n:Active`)	Values are many, dynamic, or unique per node
You traverse by type (`MATCH (n:VIPCustomer)`)	You filter by value (`WHERE n.tier = 'vip'`)
Category drives index selection	Fine-grained value drives range scans
Example: `:Active`, `:Verified`, `:Premium`	Example: `status`, `score`, `email`

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

Low-cardinality state such as status: label (:Active) if stable category used for traversal/filter; property if changes often or only returned with node. Never a (:Status) node.

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 elementId(p1) < elementId(p2)
  AND e1.startDate <= coalesce(e2.endDate, date())
  AND e2.startDate <= coalesce(e1.endDate, date())
RETURN DISTINCT 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

Relational construct	Graph equivalent	Notes
Table row	Node	One label per table (add more as needed)
Column (scalar)	Node property
Primary key	Uniqueness constraint property	Prefer `tmdbId`/`personId` over bare `id`
Foreign key	Relationship	Direction: from dependent → referenced
Many-to-many junction table	Intermediate node	Especially if junction has own columns
Junction table (no own columns)	Direct relationship	Simpler; upgrade to intermediate node later
NULL FK (optional relation)	Absent relationship	No node created; absence is the signal
Polymorphic FK (Rails-style)	Multiple labels or relationship types	Split into type-specific rels
Self-referential FK	Same-label relationship	`:Employee {managerId}` → `(e)-[:REPORTS_TO]->(m)`
Audit/history columns	Intermediate versioning node	See References for versioning pattern

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):

Strategy	When to use	Implementation
Query direction	Directional asymmetry exists	Query from low-degree side; exploit direction
Relationship type split	Supernode serves multiple roles	`:FOLLOWS` + `:FAN` instead of single `:RELATED_TO`
Label segregation	Supernode conflates entity types	`:Celebrity` vs `:User` → query only relevant subtype
Bucket pattern	Time-series or high-volume event nodes	See below
Avoid modeling	Low-cardinality categoricals	Use label instead of node (`:Active` not `(:Status {name:"Active"})`)
Join hint	Query tuning last resort	`USING JOIN ON n` in Cypher

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

Element	Convention	Good	Bad
Node label	PascalCase, singular noun	`:Person`, `:BlogPost`	`:person`, `:blog_posts`, `:Entity`
Relationship type	SCREAMING_SNAKE_CASE, verb phrase	`:ACTED_IN`, `:WORKS_FOR`	`:actedin`, `:relatedTo`, `:HAS`
Property key	camelCase	`firstName`, `createdAt`	`FirstName`, `first_name`
Constraint name	snake_case descriptive	`person_id_unique`	`constraint1`
Index name	snake_case descriptive	`person_name_idx`	`index2`

Schema Enforcement — What to Create for Each Element

Run all DDL with IF NOT EXISTS. Apply before importing data.

// 1. Uniqueness constraint — every node type used in MERGE
CREATE CONSTRAINT person_id_unique IF NOT EXISTS
  FOR (p:Person) REQUIRE p.id IS UNIQUE;

// 2. Existence constraint (Enterprise) — mandatory properties
CREATE CONSTRAINT person_name_exists IF NOT EXISTS
  FOR (p:Person) REQUIRE p.name IS NOT NULL;

// 3. Property type constraint (Enterprise) — enforce data type
CREATE CONSTRAINT person_born_integer IF NOT EXISTS
  FOR (p:Person) REQUIRE p.born IS :: INTEGER;

// 4. Key constraint (Enterprise) — unique + exists in one
CREATE CONSTRAINT movie_tmdbid_key IF NOT EXISTS
  FOR (m:Movie) REQUIRE m.tmdbId IS NODE KEY;

// 4b. Community alternative to NODE KEY — composite uniqueness (existence not enforced)
CREATE CONSTRAINT movie_title_released_unique IF NOT EXISTS
  FOR (m:Movie) REQUIRE (m.title, m.released) IS UNIQUE;

// 5. Range index — equality and range filters on properties
CREATE INDEX person_name_idx IF NOT EXISTS
  FOR (p:Person) ON (p.name);

// 6. Fulltext index — ranked free-text search via `db.index.fulltext.queryNodes` / `SEARCH` (Lucene syntax, wildcards like `An*`); not used for CONTAINS / STARTS WITH predicates
CREATE FULLTEXT INDEX person_fulltext IF NOT EXISTS
  FOR (n:Person) ON EACH [n.name, n.bio];

// 6b. Text index — serves CONTAINS / STARTS WITH / ENDS WITH (range index preferred for STARTS WITH when present)
CREATE TEXT INDEX person_bio_text IF NOT EXISTS
  FOR (n:Person) ON (n.bio);

// 7. Vector index — embedding similarity search
CREATE VECTOR INDEX chunk_embedding_idx IF NOT EXISTS
  FOR (c:Chunk) ON (c.embedding)
  OPTIONS { indexConfig: { `vector.dimensions`: 1536, `vector.similarity_function`: 'cosine' } };

// 8. Relationship index — filter on rel properties
CREATE INDEX acted_in_year_idx IF NOT EXISTS
  FOR ()-[r:ACTED_IN]-() ON (r.year);

After creating indexes, poll until ONLINE:

SHOW INDEXES YIELD name, state WHERE state <> 'ONLINE' RETURN name, state;

Do NOT use an index until state = ONLINE.

Vector / Embedding Property Modeling

Prefer dedicated :Chunk nodes for long text; short-text embeddings can live on the entity:

(:Document)-[:HAS_CHUNK]->(c:Chunk {text: "...", embedding: [...]})

Rules:

Chunk node: text (source text), embedding (float array), chunkIndex (int)
Parent document: metadata only (title, url, createdAt)
Vector index on c.embedding only
Chunk size 200–500 tokens with 20% overlap is production default [field]
Chunked docs: do NOT put embedding on :Document — makes node too large, pollutes traversal

Anti-Patterns Table

Anti-pattern	Problem	Fix
Generic labels `:Entity`, `:Node`	No filtering benefit; all nodes scan	Use domain labels `:Person`, `:Product`
Generic rel types `:RELATED_TO`, `:HAS`	Can't filter by relationship type	Use semantic types `:PURCHASED`, `:AUTHORED`
Low-cardinality value as node	Supernode (`:Status {name:"active"}` → millions of edges)	Use label `:Active` instead
Property as label (`n.type = 'VIP'` + `:VIP` label both exist)	Inconsistency, duplication	Pick one; prefer label if used in traversal
Storing embeddings on business node	Node bloat, slow traversal	Dedicated `:Chunk` node
MERGE without uniqueness constraint	Duplicate nodes silently created	Add constraint before any MERGE
Missing relationship direction meaning	Arbitrary direction; confusing model	Direction = semantic flow of action
Junction table modeled as bare property	Loses history and extensibility	Intermediate node with its own properties
`id` as property name	`id(n)` is a deprecated Cypher function (use `elementId(n)`); bare `id` is fine as a property name in practice, but domain-qualified names (`personId`, `movieId`) are clearer and avoid any future ambiguity	Prefer `personId`, `movieId`, `tmdbId` where it aids readability
All dates as strings	No range queries; no temporal operators	Use Neo4j `date()` or `datetime()` type

Output Format — Schema Assessment

When reviewing an existing model:

## Schema Assessment

### Compliant
- [constraint / pattern that is correct]

### Issues Found
#### [Title] — Severity: ERROR / WARNING / INFO
- **Current**: what the model does
- **Problem**: why it is an issue
- **Fix**: specific Cypher DDL or model change

## Recommended Schema
### Node Labels
- :Label {key: TYPE, prop: TYPE, ...}  → constraints: [list]

### Relationships
- (:LabelA)-[:TYPE {prop: TYPE}]->(:LabelB)

### Constraints to Create
[CREATE CONSTRAINT ... statements]

### Indexes to Create
[CREATE INDEX ... statements]

Severity semantics:

Severity	Meaning	Action
`ERROR`	Model correctness failure (duplicates possible, data loss risk)	Stop; fix before proceeding
`WARNING`	Performance or extensibility risk	Report; ask user before proceeding
`INFO`	Style or convention deviation	Surface; continue

Provenance Labels

[official] — stated directly in Neo4j docs
[derived] — follows from documented behavior
[field] — community heuristic; treat as default but validate

Checklist

Use cases (≥5 queries) defined before modeling
Schema inspected on existing database before changes proposed
Every MERGE-target node label has a uniqueness constraint
No generic labels (:Entity, :Node, :Thing)
No generic relationship types (:RELATED_TO, :HAS, :CONNECTED_TO)
Relationship direction encodes semantic meaning
N-ary or propertied relationships use intermediate nodes
High-cardinality values stored as properties, not nodes
Low-cardinality categoricals used as labels, not property nodes
Embeddings on dedicated :Chunk nodes, not business nodes
Supernode candidates identified and mitigated
All DDL uses IF NOT EXISTS
Indexes polled to ONLINE before use
Assessment output follows the structured format above
Every prohibition paired with a concrete fix

References

Load on demand: