使用 Python 将 CSV 数据导入 Neo4j 图数据库

本文演示了如何利用 Python 脚本结合 py2neo 库，将 CSV 格式的人物关系数据清洗并导入 Neo4j 图数据库的全过程。涵盖文件编码转换、环境依赖安装、图节点与关系的创建以及常见编码错误的排查方案。

一、数据准备

在开始之前，确保你的 CSV 文件编码正确。很多中文数据源默认是 GBK 或 ANSI，直接读取容易报错。

用记事本打开 CSV 文件。
选择'另存为'，编码格式务必选 UTF-8。
保存时确认覆盖原文件或重命名新文件。

这一步很关键，后续代码若出现 UnicodeDecodeError，通常是因为文件编码不匹配。

文章配图

二、环境搭建

1. 启动 Neo4j

本地运行 Neo4j 数据库，创建一个新的数据库实例，设置好用户名和密码（默认通常是 neo4j / password，建议修改）。

启动后进入 Browser 界面，输入以下 Cypher 语句验证连接是否成功且数据库为空：

match(n) return n;

如果返回空结果集，说明数据库已就绪。

文章配图

2. 配置 Python 项目

在 PyCharm 或其他 IDE 中创建新项目，检查解释器环境。需要安装以下核心依赖：

neo4j-python-driver: Neo4j 官方驱动
pandas: 处理 CSV 数据
py2neo: 简化图数据库操作的封装库

在 Terminal 中执行安装命令：

pip install neo4j-python-driver pandas py2neo

安装完成后，建议在 IDE 的 Settings -> Project Interpreter 中确认这些包已存在。

三、连接与测试

编写一个简单的连接测试脚本，确保 Python 能连通 Neo4j。注意替换为你实际设置的密码。

from py2neo import Graph

# 连接本地 Neo4j，端口默认为 7474
graph = Graph("bolt://localhost:7687", auth=("neo4j", "你的密码"))

# 简单查询验证
result = graph.run("MATCH (n) RETURN count(n)").data()
print(f"当前节点数：{result[0]['count(n)']}")

运行无误后，即可进行正式的数据导入。

四、核心导入逻辑

这里分为两步：先创建节点（Node），再建立关系（Relationship）。

1. 加载与解析数据

使用 Pandas 读取 CSV，提取人物和关系字段。假设 CSV 包含 人物, 关系, 关系人物 三列。

import pandas as pd

# 读取 CSV 文件，注意 encoding 参数需与文件一致
invoice_data = pd.read_csv('your_data.csv', encoding='utf-8')

# 预处理：将所有元组存入列表
tuple_total = []
for index, row in invoice_data.iterrows():
    ties_total = [row['人物'], row['关系'], row['关系人物']]
    tuple_total.append(ties_total)

print(f"共解析 {len(tuple_total)} 条关系")

2. 创建节点

遍历所有人物名称，去重后批量创建节点。为了避免重复创建，可以使用 merge 模式，但为了演示清晰，这里展示基础创建逻辑。

from py2neo import Node

people_list = list(set([row[0] for row in tuple_total] + [row[2] for row in tuple_total]))

def create_node(people):
    for name in people:
        # 定义标签为 '人物'，属性为 name
        node_1 = Node('人物', name=name)
        graph.create(node_1)

create_node(people_list)

此时回到 Neo4j Browser 查看，应该能看到一批孤立的节点。

3. 建立关系

利用 NodeMatcher 查找已存在的节点，然后构建关系对象。

from py2neo import Relationship, NodeMatcher

matcher = NodeMatcher(graph)

for i in range(len(tuple_total)):
    name_1 = matcher.match('人物', name=tuple_total[i][0]).first()
    name_2 = matcher.match('人物', name=tuple_total[i][2]).first()
    rel_type = tuple_total[i][1]
    
    if name_1 and name_2:
        relationship = Relationship(name_1, rel_type, name_2)
        graph.create(relationship)

最后再次查询图谱，观察节点间是否形成了连线。

文章配图

五、常见问题排查

UnicodeDecodeError

如果在读取 CSV 时报错 UnicodeDecodeError: 'utf-8' codec can't decode byte...，这通常意味着文件编码不是 UTF-8。

解决方案：

重新打开 CSV 文件。
另存为时强制选择 UTF-8 编码。
确保 Python 代码中的 encoding='utf-8' 与文件实际编码一致。

文章配图

通过上述步骤，你可以快速将结构化表格数据转化为图数据库中的知识网络，为后续的分析挖掘打下基础。