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

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.