图数据库驱动
图数据库驱动
相关源文件
本章引用的主要源码文件：
CODE_OF_CONDUCT.mdZep-CLA.mdexamples/langgraph-agent/agent.ipynbgraphiti_core/driver/driver.pygraphiti_core/driver/falkordb/__init__.pygraphiti_core/driver/falkordb/operations/__init__.pygraphiti_core/driver/falkordb/operations/community_edge_ops.pygraphiti_core/driver/falkordb/operations/community_node_ops.pygraphiti_core/driver/falkordb/operations/entity_edge_ops.pygraphiti_core/driver/falkordb/operations/entity_node_ops.pygraphiti_core/driver/falkordb/operations/episode_node_ops.pygraphiti_core/driver/falkordb/operations/episodic_edge_ops.pygraphiti_core/driver/falkordb/operations/has_episode_edge_ops.pygraphiti_core/driver/falkordb_driver.pygraphiti_core/driver/kuzu/operations/episode_node_ops.pygraphiti_core/driver/kuzu/operations/episodic_edge_ops.pygraphiti_core/driver/kuzu/operations/graph_ops.pygraphiti_core/driver/kuzu/operations/has_episode_edge_ops.pygraphiti_core/driver/kuzu_driver.pygraphiti_core/driver/neo4j_driver.pygraphiti_core/driver/neptune_driver.pygraphiti_core/helpers.pytests/test_graphiti_mock.py
本文档介绍了图数据库驱动的实现，这些驱动为与 Neo4j、FalkorDB、Kuzu 和 Amazon Neptune 交互提供了统一接口。驱动层抽象了数据库特定的连接管理、查询执行、会话处理和操作类。
有关每个提供商如何生成查询的详细信息，请参阅提供商特定查询生成。有关索引和约束管理，请参阅索引和约束管理。
驱动架构总览
Graphiti 使用一个抽象的 GraphDriver 类，该类为所有图数据库提供商定义了通用接口。每个具体的驱动实现负责处理提供商特定的连接协议、会话管理和查询执行语义。
代码实体映射：驱动和会话
下图将抽象的驱动接口桥接到代码库中的具体实现。
来源： graphiti_core/driver/driver.py:59-211, graphiti_core/driver/neo4j_driver.py:60-150, graphiti_core/driver/falkordb_driver.py:75-214, graphiti_core/driver/kuzu_driver.py:136-207, graphiti_core/driver/neptune_driver.py:139-251
提供商枚举
GraphProvider 枚举定义了四个支持的数据库提供商：
| 提供商 | 枚举值 | 描述 |
|---|---|---|
| Neo4j | GraphProvider.NEO4J | 全功能图数据库，使用 Bolt 协议 |
| FalkorDB | GraphProvider.FALKORDB | 基于 Redis 的图数据库，使用 RedisSearch |
| Kuzu | GraphProvider.KUZU | 嵌入式图数据库，基于文件存储 |
| Neptune | GraphProvider.NEPTUNE | AWS 托管图数据库，集成 OpenSearch |
每个驱动将其 provider 类属性设置为相应的枚举值，以便在运行时进行识别 graphiti_core/driver/driver.py:91。
来源： graphiti_core/driver/driver.py:59-64, graphiti_core/driver/driver.py:91
Neo4j 驱动实现
初始化和连接
Neo4jDriver 使用官方 neo4j Python 驱动的 AsyncGraphDatabase 接口连接到 Neo4j graphiti_core/driver/neo4j_driver.py:72-75。
连接参数：
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
uri | str | 必填 | Neo4j 连接 URI（例如 bolt://localhost:7687） |
user | str | None | 必填 | 认证用户名 |
password | str | None | 必填 | 认证密码 |
database | str | 'neo4j' | 目标数据库名称 |
驱动将 AsyncGraphDatabase 客户端存储在 self.client 中，并在初始化期间实例化所有操作类 graphiti_core/driver/neo4j_driver.py:72-89。它还通过 asyncio.create_task 调度索引构建 graphiti_core/driver/neo4j_driver.py:92-101。
来源： graphiti_core/driver/neo4j_driver.py:60-104
会话和事务支持
Neo4jDriver 提供完整的事务支持，具有真实的提交/回滚语义。transaction() 方法 graphiti_core/driver/neo4j_driver.py:151-161 使用 Neo4j 原生的 session.begin_transaction() 创建一个 _Neo4jTransaction 包装器 graphiti_core/driver/neo4j_driver.py:228-235。
来源： graphiti_core/driver/neo4j_driver.py:151-161, graphiti_core/driver/neo4j_driver.py:228-235
FalkorDB 驱动实现
初始化和连接
FalkorDriver 使用 falkordb.asyncio 包连接到 FalkorDB（基于 Redis 的图数据库）graphiti_core/driver/falkordb_driver.py:146。
连接参数：
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
host | str | 'localhost' | FalkorDB 主机地址 |
port | int | 6379 | Redis 协议端口 |
username | str | None | None | 认证用户名（可选） |
password | str | None | None | 认证密码（可选） |
database | str | 'default_db' | 用于多租户支持的图名称 |
会话和数据处理
FalkorDriverSession graphiti_core/driver/falkordb_driver.py:75-108 是 FalkorGraph 实例的轻量级包装器。它在执行前将 datetime 对象转换为 ISO 字符串 graphiti_core/driver/falkordb_driver.py:99-105，因为 FalkorDB 不支持原生 datetime 对象。
来源： graphiti_core/driver/falkordb_driver.py:75-168, graphiti_core/helpers.py:68-76
Kuzu 驱动实现
Kuzu 是一个嵌入式图数据库。KuzuDriver 初始化一个 kuzu.Database 和一个 AsyncConnection graphiti_core/driver/kuzu_driver.py:146-150。
模式强制
Kuzu 需要显式模式。驱动在初始化期间执行 setup_schema() graphiti_core/driver/kuzu_driver.py:148，该函数应用 SCHEMA_QUERIES，定义 Episodic、Entity、Community、Saga 和 RelatesToNode_ 的表 graphiti_core/driver/kuzu_driver.py:54-133。
来源： graphiti_core/driver/kuzu_driver.py:54-163
Neptune 驱动实现
NeptuneDriver 同时支持 Neptune 数据库集群（neptune-db://）和 Neptune Analytics 图（neptune-graph://）graphiti_core/driver/neptune_driver.py:154-163。它利用 Amazon OpenSearch Service（AOSS）客户端来索引和搜索节点及边的元数据 graphiti_core/driver/neptune_driver.py:169-180。
来源： graphiti_core/driver/neptune_driver.py:139-180
操作类架构
每个驱动通过属性方法公开专门的操作类。这些类封装了提供商特定的逻辑，用于对图实体执行 CRUD 操作。
代码实体映射：操作属性
来源： graphiti_core/driver/neo4j_driver.py:107-149, graphiti_core/driver/falkordb_driver.py:172-214, graphiti_core/driver/kuzu_driver.py:167-207, graphiti_core/driver/neptune_driver.py:210-251
查询执行和索引
索引和约束管理
驱动在初始化期间调度索引创建，以确保数据完整性和性能。
- Neo4j：通过事件循环调度
build_indices_and_constraintsgraphiti_core/driver/neo4j_driver.py:92-101。 - Kuzu：模式是预定义的，并在
setup_schema()期间创建graphiti_core/driver/kuzu_driver.py:148。 - FalkorDB：通过
loop.create_task调度索引构建graphiti_core/driver/falkordb_driver.py:161-168。
消毒和校验
helpers.py 模块提供了用于安全查询执行的实用工具：
lucene_sanitize：转义全文查询中的特殊字符graphiti_core/helpers.py:79-113。validate_node_labels：确保节点标签对于 Cypher 插值是安全的graphiti_core/helpers.py:174-187。validate_group_id：验证字母数字组标识符graphiti_core/helpers.py:136-160。
来源： graphiti_core/helpers.py:79-187, graphiti_core/driver/neo4j_driver.py:92-101
数据库克隆和多租户
with_database(database) 方法允许在重用底层客户端连接的同时切换目标图/数据库，通过浅拷贝实现 graphiti_core/driver/driver.py:117-125。
- Neo4j：更新
_database属性以限定会话范围graphiti_core/driver/neo4j_driver.py:169。 - FalkorDB：默认使用
\\_作为其内部表示的组 IDgraphiti_core/helpers.py:73-76。
来源： graphiti_core/driver/driver.py:117-133, graphiti_core/helpers.py:68-76