neo4j-cypher-guide

Neo4j 现代 Cypher 查询指南

此技能可帮助使用现代语法模式生成 Neo4j Cypher 只读查询，并避免使用已弃用的特性。重点介绍图遍历和数据检索的高效查询模式。

快速兼容性检查

生成 Cypher 查询时，立即避免使用以下已移除的特性：

• ❌ id() 函数 → 使用 elementId()
• ❌ 隐式分组键 → 使用显式的 WITH 子句
• ❌ 用于列表的模式表达式 → 使用模式推导式或 COLLECT 子查询
• ❌ 重复的关系变量 → 使用唯一的变量名
• ❌ 自动将列表强制转换为布尔值 → 使用显式检查

查询生成的核心原则

1. 使用现代语法模式 - 复杂遍历使用 QPP，复杂读取使用 CALL 子查询
2. 遍历时进行优化 - 在模式中尽早筛选，而不是在扩展后筛选
3. 排序时始终筛选空值 - 为排序属性添加 IS NOT NULL 检查
4. 明确优于隐式 - 始终使用显式分组和类型检查

关键排序规则

排序时始终筛选 NULL 值：

// WRONG - May include null values
MATCH (n:Node)
RETURN n.name, n.value
ORDER BY n.value

// CORRECT - Filter nulls before sorting
MATCH (n:Node)
WHERE n.value IS NOT NULL
RETURN n.name, n.value
ORDER BY n.value

查询模式选择指南

简单查询

使用具有现代语法的标准 Cypher 模式：

MATCH (n:Label {property: value})
WHERE n.otherProperty IS :: STRING
RETURN n

可变长度路径

考虑使用量化路径模式（QPP）以获得更好的性能：

// Instead of: MATCH (a)-[*1..5]->(b)
// Use: MATCH (a)-[]-{1,5}(b)

// With filtering:
MATCH (a)((n WHERE n.active)-[]->(m)){1,5}(b)

聚合

使用 COUNT{}、EXISTS{} 和 COLLECT{} 子查询：

MATCH (p:Person)
WHERE count{(p)-[:KNOWS]->()} > 5
RETURN p.name, 
       exists{(p)-[:MANAGES]->()} AS isManager

复杂读取操作

使用 CALL 子查询执行复杂的数据检索：

MATCH (d:Department)
CALL (d) {
  MATCH (d)<-[:WORKS_IN]-(p:Person)
  WHERE p.salary IS NOT NULL  // Filter nulls
  WITH p ORDER BY p.salary DESC
  LIMIT 3
  RETURN collect(p.name) AS topEarners
}
RETURN d.name, topEarners

常见查询转换

计数模式

// Old: RETURN size((n)-[]->())
// Modern: RETURN count{(n)-[]->()}

检查是否存在

// Old: WHERE exists((n)-[:REL]->())
// Modern: WHERE EXISTS {MATCH (n)-[:REL]->()}
// Also valid: WHERE exists{(n)-[:REL]->()}

元素 ID

// Old: WHERE id(n) = 123
// Modern: WHERE elementId(n) = "4:abc123:456"
// Note: elementId returns a string, not integer

处理空值的排序

// Always add null check
MATCH (n:Node)
WHERE n.sortProperty IS NOT NULL
RETURN n
ORDER BY n.sortProperty

// Or use NULLS LAST
MATCH (n:Node)
RETURN n
ORDER BY n.sortProperty NULLS LAST

何时加载参考文档

遇到以下情况时，加载相应的参考文件：

references/deprecated-syntax.md

• 将查询从较旧的 Neo4j 版本迁移过来
• 旧版查询出现语法错误
• 需要已移除或已弃用特性的完整列表

references/subqueries.md

• 使用 CALL 子查询执行读取操作
• 使用 COLLECT 或 COUNT 子查询
• 处理复杂聚合
• 实现带空值筛选的排序

references/qpp.md

• 优化可变长度路径查询
• 需要在遍历过程中尽早筛选
• 处理长度超过 3-4 跳的路径
• 有复杂的模式匹配需求

查询生成检查清单

完成任何生成的查询前，请确认：

1. ✅ 不含已弃用的函数（id、btree 索引等）
2. ✅ 聚合使用显式分组
3. ✅ 所有排序属性都有 NULL 筛选条件
4. ✅ 读取操作使用合适的子查询模式
5. ✅ 对需要筛选的路径考虑使用 QPP
6. ✅ 对模式计数使用 COUNT{}，而不是 size()
7. ✅ CALL 子查询使用变量作用域子句
8. ✅ 关系使用唯一的变量名

错误解决模式

“Implicit grouping key”错误

// Problem: RETURN n.prop, count(*) + n.other
// Solution: WITH n.prop AS prop, n.other AS other, count(*) AS cnt
//          RETURN prop, cnt + other

“id() function not found”错误

// Use elementId() but note it returns a string, not integer

“Repeated variable”错误

// Problem: MATCH (a)-[r*]->(), (b)-[r*]->()
// Solution: MATCH (a)-[r1*]->(), (b)-[r2*]->()

性能提示

1. 从索引属性开始 - 始终使用索引查找作为模式的锚点
2. 在 QPP 中尽早筛选 - 在模式中应用 WHERE 子句
3. 排序前筛选空值 - 避免意外结果并提升性能
4. 限制扩展深度 - 在量词中设置合理的上限
5. 使用 EXISTS 检查是否存在 - 比计数更高效
6. 分析查询 - 使用 PROFILE 查找瓶颈

现代 Cypher 特性

标签表达式

WHERE n:Label1|Label2  // OR
WHERE n:Label1&Label2  // AND
WHERE n:!Archived      // NOT

类型谓词

WHERE n.prop IS :: STRING
WHERE n.value IS :: INTEGER NOT NULL
WHERE n.data IS :: LIST<STRING>

用于读取的子查询模式

• COUNT{} - 高效计数模式
• EXISTS{} - 检查模式是否存在
• COLLECT{} - 收集复杂结果
• CALL{} - 执行子查询以完成复杂读取

量化路径模式

• 遍历过程中进行内联筛选
• 访问模式中的节点和关系
• 显著提升性能（最高可达 1000 倍）
• 支持复杂的多跳模式

始终优先使用现代语法模式，以获得更好的性能和可维护性。