图数据库适配器
图数据库适配器
相关源文件
本章引用的主要源码文件：
CLAUDE.mdcognee/infrastructure/databases/graph/graph_db_interface.pycognee/infrastructure/databases/graph/kuzu/adapter.pycognee/infrastructure/databases/graph/ladybug/LadybugDatasetDatabaseHandler.pycognee/infrastructure/databases/graph/ladybug/adapter.pycognee/infrastructure/databases/graph/ladybug/ladybug_migrate.pycognee/infrastructure/databases/graph/ladybug/remote_ladybug_adapter.pycognee/infrastructure/databases/graph/neo4j_driver/adapter.pycognee/infrastructure/databases/graph/neptune_driver/__init__.pycognee/infrastructure/databases/graph/neptune_driver/adapter.pycognee/infrastructure/databases/graph/neptune_driver/exceptions.pycognee/infrastructure/databases/graph/neptune_driver/neptune_utils.pycognee/infrastructure/databases/graph/postgres/__init__.pycognee/infrastructure/databases/graph/postgres/adapter.pycognee/infrastructure/databases/graph/postgres/tables.pycognee/infrastructure/databases/hybrid/neptune_analytics/NeptuneAnalyticsAdapter.pycognee/infrastructure/databases/hybrid/neptune_analytics/__init__.pycognee/infrastructure/databases/vector/chromadb/ChromaDBAdapter.pycognee/infrastructure/databases/vector/lancedb/LanceDBAdapter.pycognee/infrastructure/databases/vector/pgvector/PGVectorAdapter.pycognee/infrastructure/databases/vector/vector_db_interface.pycognee/modules/retrieval/cypher_search_retriever.pycognee/modules/retrieval/natural_language_retriever.pycognee/tasks/temporal_awareness/index_graphiti_objects.pycognee/tests/test_neptune_analytics_graph.pycognee/tests/test_neptune_analytics_hybrid.pycognee/tests/test_neptune_analytics_vector.pycognee/tests/unit/infrastructure/databases/graph/test_ladybug_migrate.pycognee/tests/unit/infrastructure/databases/test_get_unified_engine.pycognee/tests/unit/infrastructure/databases/test_neptune_analytics_hybrid.pycognee_db_workers/ladybug_migrate.pyexamples/configurations/permissions_example/data_access_control_example.pyexamples/configurations/permissions_example/tenant_role_constraints_example.pyexamples/configurations/permissions_example/tenant_role_setup_example.pyexamples/database_examples/neptune_analytics_example.pynotebooks/neptune-analytics-example.ipynb
目的与范围
本文档描述了 Cognee 中的图数据库适配器层，该层为与不同图数据库后端的交互提供了统一接口。适配器模式使 Cognee 能够通过通用的 GraphDBInterface 支持多种图数据库提供商（Ladybug/Kuzu、Neo4j、Neptune、Postgres、NetworkX）。该层对于 Cognee 的 "Cognify" 流程至关重要，在该流程中，结构化知识会被提取并以节点和边的形式持久化存储。
关于向量数据库适配器的信息，请参见向量数据库适配器。关于关系型数据库配置，请参见关系型数据库适配器。关于数据库提供商选择与工厂模式，请参见数据库配置与选择。
适配器架构总览
Cognee 使用适配器模式实现了可插拔的图数据库层。所有图数据库操作都通过 GraphDBInterface 进行，具体的适配器会为特定的数据库提供商实现该接口。这种抽象使得更高层的检索逻辑（如 GraphCompletionRetriever）无需关心底层存储是嵌入式数据库还是远程集群。
代码实体空间映射
下图将自然语言搜索意图与负责图持久化和检索的具体代码实体进行了关联。
来源： cognee/infrastructure/databases/graph/graph_db_interface.py:17-40、cognee/infrastructure/databases/graph/ladybug/adapter.py:47-56、cognee/infrastructure/databases/graph/neo4j_driver/adapter.py:52-57、cognee/infrastructure/databases/graph/postgres/adapter.py:24-25、cognee/infrastructure/databases/hybrid/neptune_analytics/NeptuneAnalyticsAdapter.py:45-52
GraphDBInterface
GraphDBInterface 抽象基类定义了所有图数据库适配器必须实现的契约。它为节点和边的操作、图遍历以及指标统计提供了统一的 API。
核心接口方法
| 方法类别 | 方法 | 用途 |
|---|---|---|
| 节点操作 | add_node()、add_nodes()、delete_node()、delete_nodes()、get_node()、get_nodes() | 节点的创建、读取、更新、删除操作 cognee/infrastructure/databases/graph/graph_db_interface.py:62-156 |
| 边操作 | add_edge()、add_edges()、has_edge()、has_edges()、get_edges() | 管理节点间的关系 cognee/infrastructure/databases/graph/graph_db_interface.py:159-230 |
| 图遍历 | get_neighbors()、get_predecessors()、get_successors()、get_connections() | 导航图结构 |
| 图查询 | query()、is_empty()、get_graph_data()、get_graph_metrics() | 执行查询并检索图信息 cognee/infrastructure/databases/graph/graph_db_interface.py:43-58 |
来源： cognee/infrastructure/databases/graph/graph_db_interface.py:42-230
支持的提供商
Ladybug（Kuzu）适配器
LadybugAdapter（原名 KuzuAdapter）使用 Kuzu 提供了基于文件的嵌入式图数据库。它是 Cognee 的默认提供商。
- 实现方式：支持本地模式和子进程代理模式，以实现资源隔离
cognee/infrastructure/databases/graph/ladybug/adapter.py:58-64。 - JSON 支持：自动处理 JSON 扩展，以存储复杂属性
cognee/infrastructure/databases/graph/ladybug/adapter.py:79-80。 - 持久化：管理
Database和Connection句柄，支持可配置的缓冲池和数据库大小cognee/infrastructure/databases/graph/ladybug/adapter.py:119-145。 - 迁移：保留
KuzuAdapter的历史导入路径，以实现向后兼容cognee/infrastructure/databases/graph/kuzu/adapter.py:1-17。
来源： cognee/infrastructure/databases/graph/ladybug/adapter.py:47-114、cognee/infrastructure/databases/graph/kuzu/adapter.py:1-23
Neo4j 适配器
Neo4jAdapter 通过 Bolt 协议连接到 Neo4j 实例。
- 标签：对所有实体使用基础标签
__Node__，以优化全局查找cognee/infrastructure/databases/graph/neo4j_driver/adapter.py:49-50。 - 约束管理：自动为节点的
id属性初始化唯一性约束cognee/infrastructure/databases/graph/neo4j_driver/adapter.py:101-107。 - 弹性：实现
@deadlock_retry()装饰器，以处理高并发写入期间的临时数据库锁cognee/infrastructure/databases/graph/neo4j_driver/adapter.py:127-128。 - 可观测性：集成 OpenTelemetry，以跟踪查询执行和行数统计
cognee/infrastructure/databases/graph/neo4j_driver/adapter.py:149-158。
来源： cognee/infrastructure/databases/graph/neo4j_driver/adapter.py:52-164
Neptune Analytics 适配器
NeptuneAnalyticsAdapter 是一个混合适配器，结合了 Neptune Analytics 的向量和图功能。
- 混合能力：扩展了
NeptuneGraphDB并实现了VectorDBInterface，为图和向量操作提供统一接口cognee/infrastructure/databases/hybrid/neptune_analytics/NeptuneAnalyticsAdapter.py:45-52。 - 向量集成：将向量集合映射到图节点，使用
neptune.algo.vectors.upsert()进行嵌入向量的持久化cognee/infrastructure/databases/hybrid/neptune_analytics/NeptuneAnalyticsAdapter.py:160-180。
来源： cognee/infrastructure/databases/hybrid/neptune_analytics/NeptuneAnalyticsAdapter.py:45-180
Postgres 图适配器
PostgresAdapter 使用两个表（graph_node 和 graph_edge）在关系型模式上实现了图结构。
- 模式：基于 SQLAlchemy 和
asyncpgcognee/infrastructure/databases/graph/postgres/adapter.py:24-33。 - 更新插入逻辑：使用 PostgreSQL 特有的
on_conflict_do_update实现高效的批量节点/边插入cognee/infrastructure/databases/graph/postgres/adapter.py:139-152。 - 限制：不支持原始 Cypher 查询。尝试调用
.query()会抛出NotImplementedErrorcognee/infrastructure/databases/graph/postgres/adapter.py:60-71。 - 搜索兼容性：自然语言搜索（Cypher 生成）和
CypherSearchRetriever在此后端上被明确禁用cognee/modules/retrieval/natural_language_retriever.py:111-119、cognee/modules/retrieval/cypher_search_retriever.py:43-47。
来源： cognee/infrastructure/databases/graph/postgres/adapter.py:1-153、cognee/modules/retrieval/cypher_search_retriever.py:34-47
查询模式与检索
图适配器主要通过 Search 模块中的各种 BaseRetriever 实现来使用。
自然语言转 Cypher
对于原生图后端（Neo4j、Ladybug），NaturalLanguageRetriever 会基于图模式使用大语言模型（LLM）生成 Cypher 查询。
来源： cognee/modules/retrieval/natural_language_retriever.py:35-105
Cypher 搜索执行
CypherSearchRetriever 允许在兼容的后端上直接执行 Cypher 查询。
- 校验：检查图引擎是否为
PostgresAdapter或PostgresHybridAdapter，如果是则抛出SearchTypeNotSupportedcognee/modules/retrieval/cypher_search_retriever.py:38-47。 - 执行：在确认图不为空后，直接调用适配器的
query()方法cognee/modules/retrieval/cypher_search_retriever.py:49-55。
来源： cognee/modules/retrieval/cypher_search_retriever.py:33-61
配置与工厂
工厂系统会根据系统配置实例化正确的适配器。
| 提供商 | 适配器类 | 是否支持 Cypher |
|---|---|---|
ladybug / kuzu | LadybugAdapter | 是 |
neo4j | Neo4jAdapter | 是 |
neptune | NeptuneAnalyticsAdapter | 是 |
postgres | PostgresAdapter | 否 |
来源： cognee/infrastructure/databases/graph/postgres/adapter.py:67-71、cognee/modules/retrieval/cypher_search_retriever.py:35-47、cognee/modules/retrieval/natural_language_retriever.py:108-119