【Python】neomodel 库： Neo4j 图数据库 ORM（对象关系映射）库

Python 中的 neomodel 库

neomodel 是一个基于 Python 的 Neo4j 图数据库 ORM（对象关系映射）库，旨在让你像使用 Django ORM 一样轻松地操作 Neo4j 数据库。它将图中的节点和关系建模为 Python 类，使图数据库的使用更加直观、优雅。

---

1. 安装 neomodel

pip install neomodel

依赖 Neo4j 数据库

你需要有正在运行的 Neo4j 服务（推荐使用 Bolt 协议，默认端口 7687）。

---

2. 快速连接 Neo4j 数据库

from neomodel import config

# 设置数据库连接地址（使用 Bolt 协议）
config.DATABASE_URL = 'bolt://neo4j:your_password@localhost:7687'

• 格式：bolt://<用户名>:<密码>@<地址>:<端口>

---

3. 定义节点模型

neomodel 中的每个节点用一个类表示，继承自 StructuredNode。

from neomodel import StructuredNode, StringProperty, IntegerProperty

class Person(StructuredNode):
    name = StringProperty(required=True)
    age = IntegerProperty()

• StringProperty() / IntegerProperty()：表示字段类型。
• required=True：表示字段必填。

---

4. 创建节点对象

alice = Person(name="Alice", age=30).save()
bob = Person(name="Bob", age=25).save()

• .save()：将对象写入 Neo4j。

---

5. 查询节点对象

# 查找第一个名字为 Alice 的人
alice = Person.nodes.get(name="Alice")

# 所有年龄大于 20 的人
people = Person.nodes.filter(age__gt=20)
for p in people:
    print(p.name, p.age)

• nodes.get(...)：查找单个节点（若无匹配会抛异常）。
• nodes.filter(...)：条件过滤，支持比较运算符。

---

6. 建立关系

在 neomodel 中，关系也可以建模为字段（RelationshipTo、RelationshipFrom、Relationship）。

from neomodel import RelationshipTo

class Person(StructuredNode):
    name = StringProperty()
    age = IntegerProperty()
    
    # 与其它 Person 之间的关系
    friends = RelationshipTo('Person', 'FRIEND')

添加关系

alice.friends.connect(bob)

遍历关系

for friend in alice.friends:
    print(friend.name)

---

7. 关系可以携带属性

from neomodel import StructuredRel, DateProperty, RelationshipTo

class Friendship(StructuredRel):
    since = DateProperty()

class Person(StructuredNode):
    name = StringProperty()
    friends = RelationshipTo('Person', 'FRIEND', model=Friendship)

添加带属性的关系

from datetime import date

alice.friends.connect(bob, {'since': date(2020, 1, 1)})

---

8. 删除节点与关系

# 删除节点
alice.delete()

# 删除关系
alice.friends.disconnect(bob)

---

9. 模型常用方法

方法 / 属性	说明
.save()	保存节点到数据库
.delete()	删除节点
.nodes.get(...)	查询单个节点（匹配条件）
.nodes.filter(...)	查询多个节点
.connect() / .disconnect()	建立或断开关系
.all()	获取所有节点
.first() / .last()	获取第一个/最后一个匹配项

---

10. 支持的属性类型

类型	用法示例
StringProperty	字符串
IntegerProperty	整数
FloatProperty	浮点数
BooleanProperty	布尔值
DateProperty	日期
DateTimeProperty	日期时间
ArrayProperty	数组
JSONProperty	JSON 对象

---

11. 进阶：使用 Cypher 查询

from neomodel import db

results, meta = db.cypher_query("MATCH (p:Person) RETURN p.name")
for row in results:
    print(row[0])

---

12. 与其他库对比

特性	neomodel	py2neo	neo4j（官方驱动）
风格	ORM 类建模	面向对象操作	底层事务式 API
复杂关系建模	支持结构化关系属性	需手动构造关系对象	需要手动管理事务
上手难度	简单	中等	偏底层，代码更繁琐
是否推荐	原型开发、建模清晰	通用图数据库开发	对事务/性能要求高场景

---

13. 总结

操作	示例
设置连接	config.DATABASE_URL = 'bolt://neo4j:pass@localhost:7687'
定义节点	class Person(StructuredNode)
创建节点	Person(name="Tom").save()
查询节点	Person.nodes.get(name="Tom")
建立关系	a.friends.connect(b)
查询关系	for p in a.friends:
删除节点	p.delete()
自定义关系属性	class Friendship(StructuredRel)

---

neomodel 是 Python 中最接近 ORM 风格的图数据库开发工具，非常适合那些希望像操作 Django ORM 一样使用 Neo4j 的开发者。它能让你更专注于图数据结构的建模，而不用频繁书写 Cypher 查询。适合原型开发、中小型项目、教学、知识图谱建模等场景。