agentic_huge_data_base / wiki
页面 Graphiti · 4.5 数据库抽象层·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 4.5

4.5 · 数据库抽象层（Database Abstraction Layer）

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节4.5 状态全文译文 模块检索、召回与索引、界面与交互、图谱与关系、系统架构
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节Database Abstraction Layer 上一章4.4 下一章5
源码线索
  • 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/record_parsers.py
  • graphiti_core/driver/search_interface/search_interface.py
  • graphiti_core/graph_queries.py
  • graphiti_core/helpers.py
模块标签
  • 检索、召回与索引
  • 界面与交互
  • 图谱与关系
  • 系统架构
  • 测试、发布与运维

章节正文

数据库抽象层

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/4.5-database-abstraction-layer

数据库抽象层

相关源文件

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

  • 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/record_parsers.py
  • graphiti_core/driver/search_interface/search_interface.py
  • graphiti_core/graph_queries.py
  • graphiti_core/helpers.py

目的与范围

数据库抽象层提供了一个统一接口，用于与多个图数据库后端进行交互。该抽象层使 Graphiti 能够支持 Neo4j、FalkorDB、Kuzu 和 Amazon Neptune，在切换数据库提供方时无需修改应用层代码。

本文档记录了 GraphDriver 接口、每个提供方的实现方式，以及封装了数据库特定查询逻辑的专用操作类。

来源： graphiti_core/driver/driver.py:1-221、graphiti_core/driver/neo4j_driver.py:1-236、graphiti_core/driver/falkordb_driver.py:1-423

架构总览

该抽象层采用三层架构：GraphDriver 基类定义了通用接口，提供方特定的驱动程序实现负责数据库连接和查询执行，而专用操作类则封装了节点/边相关的查询逻辑。

组件关系
Graphiti · 组件关系 · 图 1
Graphiti · 组件关系 · 图 1

来源： graphiti_core/driver/driver.py:90-211、graphiti_core/driver/neo4j_driver.py:60-149、graphiti_core/driver/falkordb_driver.py:109-214

GraphDriver 基类

GraphDriver 抽象类定义了所有数据库提供方必须实现的核心接口。每个驱动程序都维护着与后端的连接，暴露操作类，并提供用于查询执行和生命周期管理的方法。

核心接口方法
方法用途返回类型
execute_query(cypher_query_, **kwargs)执行带参数的 Cypher 查询Coroutine graphiti_core/driver/driver.py:102-103
session(database)创建数据库会话GraphDriverSession graphiti_core/driver/driver.py:106-107
close()关闭数据库连接Coroutine graphiti_core/driver/driver.py:109-111
build_indices_and_constraints(delete_existing)创建数据库索引Coroutine graphiti_core/driver/driver.py:127-129
transaction()创建事务上下文管理器AsyncIterator[Transaction] graphiti_core/driver/driver.py:146-161
clone(database)使用不同的数据库名称克隆驱动程序GraphDriver graphiti_core/driver/driver.py:131-133
提供方标识

每个驱动程序实现都定义了影响查询生成和多租户的关键类属性：

class GraphDriver(ABC):
    provider: GraphProvider  # 枚举：NEO4J、FALKORDB、KUZU、NEPTUNE
    default_group_id: str    # 默认组标识符（'' 或 '\\_'）
    fulltext_syntax: str     # 全文查询前缀（Neo4j 为 ''，FalkorDB 为 '@'）

GraphProvider 枚举用于区分支持的后端 graphiti_core/driver/driver.py:59-64。default_group_id 根据数据库类型进行区分；例如，FalkorDB 需要 \\_，而其他数据库使用空字符串 graphiti_core/helpers.py:68-76。

来源： graphiti_core/driver/driver.py:90-143、graphiti_core/driver/neo4j_driver.py:60-76、graphiti_core/driver/falkordb_driver.py:109-159、graphiti_core/helpers.py:68-76

GraphDriverSession

GraphDriverSession 抽象类提供了基于会话的数据库访问方式。会话管理查询执行，并通过 execute_write 方法支持类似事务的操作。

提供方特定的会话实现

Neo4j： 使用原生 AsyncGraphDatabase.session()，支持真正的 ACID 事务 graphiti_core/driver/neo4j_driver.py:154-155。

FalkorDB： FalkorDriverSession 包装了一个 FalkorGraph 实例 graphiti_core/driver/falkordb_driver.py:78-79。查询会立即执行，不支持原生多查询事务。execute_write 方法直接等待提供的异步函数 graphiti_core/driver/falkordb_driver.py:92-94。它还通过将日期时间转换为字符串来处理查询规范化 graphiti_core/driver/falkordb_driver.py:99-105。

来源： graphiti_core/driver/driver.py:66-88、graphiti_core/driver/falkordb_driver.py:75-108、graphiti_core/driver/neo4j_driver.py:151-161

操作类

Graphiti 将数据库操作分离到专用的操作类中，每个类负责特定的节点或边类型。这种设计使得在保持一致 API 的同时，可以实现提供方特定的查询逻辑。

操作访问模式

每个 GraphDriver 通过属性暴露操作实例。这使得核心客户端可以调用数据库特定的逻辑，而无需了解底层提供方：

@property
def entity_node_ops(self) -> EntityNodeOperations:
    return self._entity_node_ops

@property
def search_ops(self) -> SearchOperations:
    return self._search_ops

该模式在所有提供方中一致实现：

  • Neo4j： graphiti_core/driver/neo4j_driver.py:107-149
  • FalkorDB： graphiti_core/driver/falkordb_driver.py:172-214

来源： graphiti_core/driver/driver.py:168-211、graphiti_core/driver/neo4j_driver.py:78-89、graphiti_core/driver/falkordb_driver.py:147-158

提供方实现

Neo4jDriver

连接： 使用 neo4j.AsyncGraphDatabase.driver()，需要 URI 和认证信息 graphiti_core/driver/neo4j_driver.py:72-75。 事务支持： 通过 async with driver.transaction() 提供完整的 ACID 事务支持，该方法使用 _Neo4jTransaction 包装原生 Neo4j 事务 graphiti_core/driver/neo4j_driver.py:151-161。 索引管理： 在初始化期间异步调度索引创建 graphiti_core/driver/neo4j_driver.py:92-101。

FalkorDriver

连接： 使用 falkordb.asyncio.FalkorDB graphiti_core/driver/falkordb_driver.py:146。 查询执行： 使用 convert_datetimes_to_strings 转换参数，因为 FalkorDB 不支持查询参数中的原生日期时间对象 graphiti_core/driver/falkordb_driver.py:99-105。 全文语法： 使用类似 RedisSearch 的语法，在全文查询中使用 @ 符号 graphiti_core/driver/falkordb_driver.py:113。

来源： graphiti_core/driver/neo4j_driver.py:64-103、graphiti_core/driver/falkordb_driver.py:115-169

查询生成与提供方特定语法

不同的数据库提供方需要不同的 Cypher 语法变体。系统使用专用操作类来桥接抽象需求与具体实现之间的差距。

自然语言空间到代码实体空间：节点检索

此图展示了检索片段的请求如何解析为不同提供方的具体操作。

Graphiti · 自然语言空间到代码实体空间：节点检索 · 图 2
Graphiti · 自然语言空间到代码实体空间：节点检索 · 图 2

来源： graphiti_core/driver/graph_operations/graph_operations.py:200-226、graphiti_core/driver/neo4j_driver.py:112-114、graphiti_core/driver/falkordb_driver.py:150-150

自然语言空间到代码实体空间：搜索

此图展示了搜索意图如何映射到搜索操作接口和提供方实现。

Graphiti · 自然语言空间到代码实体空间：搜索 · 图 3
Graphiti · 自然语言空间到代码实体空间：搜索 · 图 3

来源： graphiti_core/driver/search_interface/search_interface.py:22-34、graphiti_core/driver/neo4j_driver.py:144-145、graphiti_core/driver/falkordb_driver.py:158-158

索引与约束管理

索引通过 get_range_indices 和 get_fulltext_indices 进行管理。这些函数会返回适用于指定 GraphProvider 的 DDL 语句。

提供方范围索引语法全文索引实现
Neo4jCREATE INDEX ... IF NOT EXISTS graphiti_core/graph_queries.py:55-63CREATE FULLTEXT INDEX ... graphiti_core/graph_queries.py:131-136
FalkorDBCREATE INDEX FOR ... ON ... graphiti_core/graph_queries.py:32-48CALL db.idx.fulltext.createNodeIndex(...) graphiti_core/graph_queries.py:98-104
Kuzu通过 SCHEMA_QUERIES 处理CALL CREATE_FTS_INDEX(...) graphiti_core/graph_queries.py:125-128

来源： graphiti_core/graph_queries.py:28-140

事务支持

不同提供方的事务支持差异很大。抽象层提供了统一的 async with driver.transaction() 接口，同时处理提供方特定的语义。

提供方事务类型提交/回滚实现
Neo4jACID 事务是_Neo4jTransaction，支持提交/回滚 graphiti_core/driver/neo4j_driver.py:151-161
FalkorDB立即执行否_SessionTransaction（查询立即执行） graphiti_core/driver/driver.py:213-221

不支持原生事务的驱动程序使用 _SessionTransaction 回退方案，该方案提供相同的接口，但通过会话立即执行查询 graphiti_core/driver/driver.py:162-166。

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

工具函数

抽象层包含多个用于数据消毒和校验的辅助函数：

  • lucene_sanitize：在将查询传递给 Lucene 进行全文搜索之前，转义其中的特殊字符 graphiti_core/helpers.py:79-113。
  • parse_db_date：规范化 Neo4j 原生 DateTime 对象与 ISO 字符串之间的日期格式 graphiti_core/helpers.py:58-65。
  • validate_node_labels：使用 SAFE_CYPHER_IDENTIFIER_PATTERN 确保节点标签可以安全地插入到 Cypher 表达式中 graphiti_core/helpers.py:174-186。
  • semaphore_gather：一个使用信号量限制并发数据库操作的工具函数（默认限制为 20，通过 SEMAPHORE_LIMIT 设置） graphiti_core/helpers.py:123-133。
  • get_default_group_id：返回 FalkorDB 的 \\_ 和其他提供方的 '' 的逻辑 graphiti_core/helpers.py:68-77。

来源： graphiti_core/helpers.py:38-186