设计或重构 Neo4j 图数据模型时…

在从零设计、评审或迁移 Neo4j 图模型时，提供节点/关系/属性/标签的决策规则、中间节点、超级节点治理、约束与索引落地及结构化评审输出。

适用场景

解决思路

1. 先列出模型必须回答的 5 个以上查询用例，再开始设计。
2. 节点 = 有身份、可作为查询入口的实体（名词）；关系 = 有方向的连接（动词）。
3. 命名规范：标签用 PascalCase；关系类型用 SCREAMING_SNAKE_CASE；属性用 camelCase。
4. 每个会在 MERGE 中使用的节点类型，都必须在其键属性上建唯一性约束。
5. 已知类型时添加属性类型约束（REQUIRE n.prop IS :: STRING），帮助查询规划器并尽早拦截错误写入。
6. 禁止通用标签（:Entity、:Node、:Thing）和通用关系类型（:RELATED_TO、:HAS）。
7. 用于行级访问控制的安全标签应以统一前缀开头（如 Sec），便于应用代码从领域模式中过滤掉。
8. 关系方向必须编码语义含义，不能随意指定。
9. 在已有数据库上提出任何变更前，先检查当前 schema。
10. 所有约束/索引 DDL 都使用 IF NOT EXISTS，保证可重复执行。
11. 在 Neo4j 2026.06+（Enterprise/Aura，GA）上，用 ALTER CURRENT GRAPH TYPE SET { … } 一次性声明完整模型，用 ALTER CURRENT GRAPH TYPE ADD { … } 扩展，而不是逐条 CREATE CONSTRAINT；2026.02–2026.05 该语法为预览。
12. 按决策表判断建模方式：有身份且作为查询入口的实体→节点；两个实体间有方向的连接→关系；连接自身有属性或有多个目标→中间节点；始终随父节点返回、从不单独过滤的标量→父节点属性；用于类型过滤或路径遍历的类别→标签（而非属性）；同一属性值在许多节点上重复（低基数）→标签而非属性节点；连接超过 2 个实体的事实→中间节点。
13. 属性 vs 标签决策：值少、固定、用于遍历过滤（WHERE n:Active）或按类型遍历（MATCH (n:VIPCustomer)）时用标签；值多、动态、每节点唯一或按值过滤（WHERE n.tier = 'vip'）时用属性。高基数值绝不要建模为标签。
14. 当关系需要自身属性、连接超过 2 个实体或需要被独立查询时，把关系提升为中间节点，例如把 (Person)-[:ACT#ED_IN {role}]->(Movie) 改为 (Person)-[:PLAYED]->(Role {name})-[:IN]->(Movie)。
15. 关系属性超过 2 个、关系本身是其他查询的主体、多个实体共享同一连接上下文、或需在一个事实中连接超过 2 个实体时，使用中间节点。
16. 关系型→图迁移：表行→节点（每表一个标签）；标量列→节点属性；主键→唯一性约束属性（用 tmdbId 而非 id）；外键→关系（方向从依赖方指向被引用方）；多对多连接表→中间节点（尤其连接表有自身列时）；无自身列的连接表→直接关系；NULL 外键→不创建关系，缺失即信号；多态外键→多个标签或关系类型；自引用外键→同标签关系（如 (e)-[:REPORTS_TO]->(m)）；审计/历史列→中间版本节点。
17. 用 MATCH (n) RETURN labels(n), elementId(n), count{ (n)--() } AS degree ORDER BY degree DESC LIMIT 10 检测超级节点；某标签节点的度远高于中位数即为候选，超过 10 万条关系的节点会拖慢穿越查询。
18. 超级节点缓解按优先级：查询方向（从低度一侧查询，利用方向不对称）；拆分关系类型（如 :FOLLOWS + :FAN 替代单一 :RELATED_TO）；标签隔离（:Celebrity 与 :User 分开，只查相关子类型）；桶模式（时间序列/高流量事件）；避免建模（低基数类别用标签而非节点）；查询调优最后手段用 USING JOIN ON n。
19. 桶模式示例：把 (:User)-[:VIEWED]->(:Page) 改为 (u:User)-[:VIEWED_IN]->(b:ViewBucket {userId, hour})-[:VIEWED]->(p:Page)，查询最近一小时时直接匹配对应桶，避免遍历全部历史。
20. 按元素创建 schema 约束：1) 唯一性约束（每个 MERGE 目标节点）；2) 存在性约束（Enterprise，必填属性）；3) 属性类型约束（Enterprise）；4) 键约束（Enterprise，唯一+存在合一）；5) 范围索引（等值与范围过滤）；6) 全文索引（CONTAINS、STARTS WITH、自由文本）；7) 向量索引（嵌入相似度搜索）；8) 关系索引（按关系属性过滤）。
21. 创建索引后用 SHOW INDEXES YIELD name, state WHERE state <> 'ONLINE' RETURN name, state 轮询，state = ONLINE 之前不要使用该索引。
22. 向量/嵌入建模：把嵌入存在专用 :Chunk 节点上，绝不放业务节点；Chunk 节点含 text、embedding、chunkIndex；父文档只存元数据（title、url、createdAt）；向量索引只建在 c.embedding 上；chunk 大小 200–500 token、20% 重叠为生产默认。
23. 避免反模式：通用标签/通用关系类型→改用领域标签与语义类型；低基数值建模为节点→改用标签；属性与标签重复表达同一分类→二选一，遍历时优先标签；嵌入存业务节点→改用专用 :Chunk 节点；MERGE 前无唯一性约束→先加约束；关系方向无意义→方向即语义流；连接表被建模为裸属性→改用带自身属性的中间节点；属性名用 id→优先 personId、movieId、tmdbId 等限定名；日期全用字符串→改用 Neo4j date() 或 datetime() 类型。
24. 评审已有模型时按固定格式输出：## Schema Assessment，分 Compliant、Issues Found（每条含 Title、Severity、Current、Problem、Fix）、Recommended Schema（Node Labels、Relationships、Constraints to Create、Indexes to Create）。
25. 严重级别语义：ERROR = 模型正确性失败（可能重复、有数据丢失风险），停止并先修复；WARNING = 性能或扩展性风险，报告并询问用户后再继续；INFO = 风格或约定偏差，提示后继续。
26. 每条禁止项都要配一个具体修复方案。
27. 完成前对照检查清单：用例≥5 个、已有库先检查 schema、每个 MERGE 目标有唯一性约束、无通用标签、无通用关系类型、方向有语义、n 元或带属性关系用中间节点、高基数值存属性、低基数类别用标签、嵌入在专用 :Chunk 节点、超级节点已识别并缓解、DDL 全用 IF NOT EXISTS、索引轮询到 ONLINE、评审输出符合格式、每条禁止项有具体修复。

适用边界 · 注意事项

• 编写或优化 Cypher 查询时（应使用 neo4j-cypher-skill）。
• 做 Spring Data Neo4j 实体映射（@Node、@Relationship）时（应使用 neo4j-spring-data-skill）。
• 定义 GraphQL 类型或导入数据（LOAD CSV、APOC import）时（应分别使用 neo4j-graphql-skill、neo4j-import-skill）。