本文详解如何通过 unwind 批处理、合理分批与参数化查询，显著提升 neo4j python 驱动在导入数十万级节点/关系时的性能，避免逐行执行导致的严重性能衰减。
在使用 Neo4j Python 官方驱动（neo4j==5.20+）进行大规模数据写入时，最常见的性能陷阱是对每一行数据单独发起一次事务（如 session.execute_write(create_entity, row)）。这种方式虽逻辑清晰，但会因网络往返开销、事务启动/提交成本及驱动序列化负担，使吞吐量急剧下降——尤其当数据量超过 10 万行时，耗时可能呈线性甚至超线性增长。
根本优化思路是：将多行数据打包为单次 Cypher 查询，利用 UNWIND 子句在服务端展开批量操作。这不仅大幅减少请求次数，还让 Neo4j 引擎能复用执行计划、优化内存分配，并支持原子性批量提交。
✅ 推荐实践：UNWIND + 分批提交
以下是一个生产就绪的示例，适用于从 Pandas DataFrame 或 CSV 文件批量创建节点：
import pandas as pd
from neo4j import GraphDatabase
from tqdm import tqdm
# 初始化驱动（建议复用全局实例）
driver = GraphDatabase.driver(
"bolt://localhost:7687",
auth=(os.getenv("NEO_USERNAME"), os.getenv("NEO_PASSWORD"))
)
# 核心批量写入 Cypher（使用 MERGE 确保唯一性，并统一更新时间戳）
query = """
UNWIND $rows AS row
MERGE (e:Entity {EntityId: row.entity_id})
ON CREATE SET e.LastAccess = timestamp()
ON MATCH SET e.LastAccess = timestamp()
"""
BATCH_SIZE = 5_000 # 根据内存与响应稳定性调整（通常 1k–10k）
def batch_write_entities(df: pd.DataFrame):
for i in tqdm(range(0, len(df), BATCH_SIZE), desc="Writing batches"):
batch_df = df.iloc[i : i + BATCH_SIZE]
# 转为字典列表，字段名需与 Cypher 中 row.xxx 严格一致
batch_data = batch_df[["entity_id"]].to_dict(orient="records")
try:
driver.execute_query(
query,
rows=batch_data,
database_="neo4j" # 显式指定数据库（v5.9+ 推荐）
)
except Exception as e:
print(f"Batch {i//BATCH_SIZE} failed: {e}")
raise
# 调用示例
batch_write_entities(df)⚠️ 关键注意事项：避免在循环中新建 Session：driver.execute_query() 内部自动管理会话与事务，无需手动 with session:；频繁创建 session 反而增加开销。字段映射必须精确：row.entity_id 中的 entity_id 必须与 DataFrame 列名完全一致（区分大小写），否则报 ParameterNotFoundException。约束先行：确保唯一性约束（如 CREATE CONSTRAINT ON (e:Entity) ASSERT e.EntityId IS UNIQUE）已在导入前建立，否则 MERGE 性能将严重劣化。内存与错误平衡：BATCH_SIZE 过大（如 >20k）可能导致 OOM 或单次失败影响过大；建议从 5k 开始压测调优。关系批量写入同理：对关系，使用双 MATCH + UNWIND，例如：UNWIND $rels AS rel MATCH (a:Entity {EntityId: rel.start_id}) MATCH (b:Entity {EntityId: rel.end_id}) CREATE (a)-[:HAS_REL]->(b)
? 补充建议
- 若数据源为 CSV 文件且无复杂预处理，可直接使用 LOAD CSV（服务端导入），速度更快，但需文件位于 Neo4j 服务器本地；
- 对于超大规模（千万级+），考虑结合 APOC 库的 apoc.periodic.iterate 实现流式分页；
- 始终参考官方 Python Driver 性能指南 与 Cypher 批量导入最佳实践。
通过以上重构，原本需数小时完成的 20 万行写入，通常可在 1–2 分钟内完成，性能提升可达 50–100 倍。核心在于：让数据“流动”起来，而非逐个“敲门”。
立即学习“Python免费学习笔记（深入）”；
