调用apoc.periodic.iterate出现Java堆内存错误的原因排查

该场景下的Java堆内存溢出不属于内存泄漏，是APOC配置偏差、Cypher写法问题叠加运行环境特性导致的全量数据驻留内存，核心触发点有三个：

• apoc.periodic.iterate默认配置未启用流式分批：Neo4j 4.4配套的APOC版本中，该存储过程默认参数iterateList值为true，此模式下会先将外层驱动查询（即匹配TEMP_RELATION的MATCH语句）的所有结果一次性拉取到堆内存生成完整Java列表，再按batchSize切分批次执行，根本不会做边拉取边执行的流式迭代，只要TEMP_RELATION关系量级达到百万级，8G堆内存会被这一步的全量结果集直接占满，这也是你观察到“分批逻辑未生效”的核心原因。
• 内层语句返回值导致内存无法回收：你内层创建关系的语句末尾写了YIELD rel RETURN rel，该写法会让所有批次新创建的关系对象一直驻留内存，等待整个存储过程执行完成后统一返回给客户端，单批次执行完成后对应的内存无法被GC回收，内存占用会随迭代推进线性上涨。
• Apple Silicon环境的额外内存开销：Neo4j 4.4.8是较早适配M1芯片的版本，配套的ARM架构JVM存在内存页对齐的额外开销，APOC执行关系属性拷贝时的临时内存占用比x86架构高25%~30%，进一步压缩了8G堆的可用空间。

调整存储过程配置参数，移除内层语句的返回逻辑，优化后的执行语句如下：

:auto CALL apoc.periodic.iterate(
    "MATCH (source:Entity)-[r:TEMP_RELATION]->(target:Entity) RETURN source, r, target",
    "CALL apoc.create.relationship(source, r.`Interaction-type`, r, target) YIELD rel SET rel.__create_flag = true",
    {
        batchSize: 2000,
        iterateList: false,
        parallel: false
    }
);

参数说明：

• iterateList: false：关闭全量结果收集，启用流式拉取，真正实现边匹配边分批执行
• batchSize: 2000：原配置5的批次大小会产生过多事务开销，写场景下1000~5000的批次大小性能最优
• parallel: false：关系创建属于写操作，开启并行会触发节点锁冲突，保持默认关闭即可

新关系创建完成后，可删除临时标记字段__create_flag，确认数据无误后批量删除原TEMP_RELATION关系即可释放冗余空间。

调整配置后可通过Neo4j debug日志观察堆内存变化：正常流式执行时，单批次事务提交后堆内存会回落到稳定基线，不会出现持续线性上涨的情况。如果你的TEMP_RELATION关系量级超过5000万，可将最大堆内存调整为12G再执行，进一步提升稳定性。

内容的提问来源于stack exchange，提问作者Martin Preusse