跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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:

OperationTool
Inspect schemaget-schema
SHOW CONSTRAINTS, SHOW INDEXESread-cypher
CREATE CONSTRAINT ... IF NOT EXISTSwrite-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 type known — catches bad writes early. Enterprise only; Community: use uniqueness constraints, validate types in app
  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 — 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

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

Property vs Label — Decision Table

Use label whenUse 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 selectionFine-grained value drives range scans
Example: :Active, :Verified, :PremiumExample: 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
阅读完整来源 ↗