7 · 数据库集成（Database Integration）

数据库集成

数据库集成

相关源文件

本章引用的主要源码文件：

• graphiti_core/driver/driver.py
• graphiti_core/driver/falkordb_driver.py
• graphiti_core/driver/graph_operations/graph_operations.py
• graphiti_core/driver/neo4j_driver.py
• graphiti_core/driver/search_interface/search_interface.py
• graphiti_core/helpers.py

本文档介绍了 Graphiti 的数据库抽象层，该层通过统一接口支持多种图数据库后端。系统目前支持 Neo4j、FalkorDB、Kuzu 和 Amazon Neptune，用户可以根据部署需求选择最适合的数据库。

有关具体提供程序实现和连接处理的详细信息，请参见图数据库驱动。有关索引创建和优化，请参见索引与约束管理。有关数据库特定的查询语法适配，请参见提供程序特定的查询生成。

GraphDriver 架构

Graphiti 通过定义在 graphiti_core/driver/driver.py:90-211 中的 GraphDriver 基类来抽象数据库操作。该抽象通过继承 QueryExecutor graphiti_core/driver/driver.py:90，使相同的应用程序代码能够无缝地在不同的图数据库提供程序之间工作。

核心驱动接口

GraphDriver 抽象基类定义了所有数据库实现必须遵守的契约：

关键抽象方法：

• execute_query(cypher_query_, **kwargs) - 执行查询并返回结果 graphiti_core/driver/driver.py:101-103。
• session(database) - 创建用于执行查询的数据库会话 graphiti_core/driver/driver.py:105-107。
• build_indices_and_constraints(delete_existing) - 初始化数据库模式 graphiti_core/driver/driver.py:127-129。
• close() - 清理数据库连接 graphiti_core/driver/driver.py:109-111。

关键属性：

• provider: GraphProvider - 标识数据库类型的枚举（NEO4J、FALKORDB、KUZU、NEPTUNE）graphiti_core/driver/driver.py:91。
• _database: str - 默认数据库/图名称 graphiti_core/driver/driver.py:95。
• default_group_id: str - 提供程序特定的默认组标识符 graphiti_core/driver/driver.py:96。
• fulltext_syntax: str - 提供程序特定的全文查询前缀（例如，FalkorDB 使用 @）graphiti_core/driver/driver.py:92-94。

来源：graphiti_core/driver/driver.py:59-143

GraphProvider 枚举

GraphProvider 枚举定义了支持的数据库后端 graphiti_core/driver/driver.py:59-64：

class GraphProvider(Enum):
    NEO4J = 'neo4j'
    FALKORDB = 'falkordb'
    KUZU = 'kuzu'
    NEPTUNE = 'neptune'

每个提供程序具有不同的特性和默认配置：

来源：graphiti_core/driver/driver.py:59-64、graphiti_core/driver/falkordb_driver.py:111-113、graphiti_core/driver/neo4j_driver.py:61-62、graphiti_core/helpers.py:68-77

操作接口模式

Graphiti 将数据库操作组织到由 GraphOperationsInterface graphiti_core/driver/graph_operations/graph_operations.py:22 定义的专门化操作类中。这种模式将查询逻辑与驱动实现分离，每个驱动实例化其特定版本的操作。

GraphDriver 操作架构

来源：graphiti_core/driver/driver.py:168-210、graphiti_core/driver/neo4j_driver.py:78-89、graphiti_core/driver/falkordb_driver.py:148-159、graphiti_core/driver/graph_operations/graph_operations.py:22-34

支持的数据库提供程序

Neo4jDriver

Neo4jDriver 类通过官方 AsyncGraphDatabase 驱动使用 Bolt 协议提供与 Neo4j 的集成 graphiti_core/driver/neo4j_driver.py:72。

连接参数：

• uri: str - Neo4j 连接 URI（例如，bolt://localhost:7687）。
• user: str | None - 认证用户名。
• password: str | None - 认证密码。
• database: str - 目标数据库名称（默认值：'neo4j'）。

来源：graphiti_core/driver/neo4j_driver.py:60-76

FalkorDriver

FalkorDriver 类集成了 FalkorDB（一种基于 Redis 的图数据库）。它通过 FalkorDB 和 FalkorGraph 支持异步查询执行 graphiti_core/driver/falkordb_driver.py:27-28。

连接参数：

• host: str、port: int - Redis/FalkorDB 实例的连接详情。
• falkor_db: FalkorDB | None - 要使用的现有 FalkorDB 实例，而不是创建新实例 graphiti_core/driver/falkordb_driver.py:142-144。
• database: str - 要连接的图名称（默认值：'default_db'）graphiti_core/driver/falkordb_driver.py:138。

来源：graphiti_core/driver/falkordb_driver.py:110-146

会话与事务管理

GraphDriverSession

GraphDriverSession 抽象基类定义了会话生命周期管理 graphiti_core/driver/driver.py:66。会话表示用于执行查询的连接上下文。

会话生命周期与代码实体

来源：graphiti_core/driver/driver.py:66-88、graphiti_core/driver/driver.py:146-167

事务支持

Graphiti 通过 transaction() 异步上下文管理器提供事务支持 graphiti_core/driver/driver.py:147。不同提供程序的能力差异很大：

1. Neo4j：使用 _Neo4jTransaction 提供真正的 ACID 事务支持，具有 begin_transaction()、commit() 和 rollback() 语义 graphiti_core/driver/neo4j_driver.py:151-161。
2. FalkorDB/Kuzu：使用回退的 _SessionTransaction，其中查询会立即针对会话执行 graphiti_core/driver/driver.py:213-220。

来源：graphiti_core/driver/driver.py:146-167、graphiti_core/driver/neo4j_driver.py:151-161

索引与约束管理

所有驱动都实现 build_indices_and_constraints() 以在启动时初始化数据库模式。像 Neo4jDriver 这样的驱动会在初始化期间将此任务调度到事件循环中 graphiti_core/driver/neo4j_driver.py:91-101。

关键索引名称：

• ENTITY_INDEX_NAME：实体节点的默认索引 graphiti_core/driver/driver.py:53。
• EPISODE_INDEX_NAME：事件节点的默认索引 graphiti_core/driver/driver.py:54。
• COMMUNITY_INDEX_NAME：社区节点的默认索引 graphiti_core/driver/driver.py:55。
• ENTITY_EDGE_INDEX_NAME：实体边的默认索引 graphiti_core/driver/driver.py:56。

来源：graphiti_core/driver/driver.py:53-56、graphiti_core/driver/neo4j_driver.py:91-101、graphiti_core/driver/falkordb_driver.py:161-168

提供程序特定的查询生成

Graphiti 会生成针对目标数据库特定方言定制的 Cypher 查询。这包括通过 parse_db_date graphiti_core/helpers.py:58-65 处理日期解析差异，以及用于全文搜索的 Lucene 消毒 graphiti_core/helpers.py:79-113。

来源：graphiti_core/driver/falkordb_driver.py:96-107、graphiti_core/driver/neo4j_driver.py:163-176、graphiti_core/helpers.py:58-113