neo4j-modeling-skill
Design, review, and refactor Neo4j graph data models. Use when choosing node
neo4j-contrib · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add neo4j-contrib/neo4j-skills --skill neo4j-modeling-skill技能说明
name: neo4j-modeling-skill description: Design, review, and refactor Neo4j graph data models. Use when choosing node labels vs relationship types vs properties, migrating relational/document schemas to graph, detecting anti-patterns (generic labels, supernodes, missing constraints), designing intermediate nodes for n-ary relationships, enforcing schema with constraints and indexes, or assessing an existing model against graph modeling best practices. Does NOT handle Cypher query authoring — use neo4j-cypher-skill. Does NOT handle Spring Data Neo4j entity mapping — use neo4j-spring-data-skill. Does NOT handle GraphQL type definitions — use neo4j-graphql-skill. Does NOT handle data import — use neo4j-import-skill. version: 1.0.7 allowed-tools: WebFetch Bash
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 withALTER CURRENT GRAPH TYPE ADD { … }, instead of individualCREATE CONSTRAINTstatements — details inneo4j-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.end
阅读完整来源 ↗