agentic_huge_data_base / wiki
页面 Cognee · 8.4 关系型模式定义·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 8.4

8.4 · 关系型模式定义（Relational Schemas）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节8.4 状态全文译文 模块存储与持久化、检索、召回与索引、模型调用与提供方适配、配置治理
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节Relational Schemas 上一章8.3 下一章9
源码线索
  • cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py
  • cognee/infrastructure/databases/graph/neo4j_driver/Neo4jAuraDevDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/graph/postgres/PostgresGraphDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/relational/config.py
  • cognee/infrastructure/databases/relational/create_relational_engine.py
  • cognee/infrastructure/databases/relational/get_relational_engine.py
  • cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py
  • cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py
  • cognee/modules/data/methods/get_dataset_databases.py
模块标签
  • 存储与持久化
  • 检索、召回与索引
  • 模型调用与提供方适配
  • 配置治理
  • 系统架构

章节正文

关系型模式定义

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/8.4-relational-schemas

关系型模式

相关源文件

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

  • cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py
  • cognee/infrastructure/databases/graph/neo4j_driver/Neo4jAuraDevDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/graph/postgres/PostgresGraphDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/relational/config.py
  • cognee/infrastructure/databases/relational/create_relational_engine.py
  • cognee/infrastructure/databases/relational/get_relational_engine.py
  • cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py
  • cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py
  • cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py
  • cognee/modules/data/methods/get_dataset_databases.py
  • cognee/modules/search/operations/get_history.py
  • cognee/run_migrations.py
  • cognee/tests/unit/infrastructure/databases/relational/test_RelationalConfig.py
  • cognee/tests/unit/infrastructure/databases/relational/test_SqlAlchemyAdapter.py
  • cognee/tests/unit/infrastructure/databases/relational/test_create_relational_engine.py
  • cognee/tests/unit/test_run_migrations.py

目的与范围

本文档描述了 Cognee 基于 SQLAlchemy 的持久化系统中使用的关系型数据库模式及其基础设施层。这些模式定义了元数据存储、数据集管理、用户认证以及多租户访问控制的结构。

关系型层负责以下功能：

  • 数据集与数据追踪：管理原始文件与逻辑数据集之间的关系 cognee/modules/data/models/Data.py:12-48、cognee/modules/data/models/DatasetData.py:1-15。
  • 用户管理：认证与租户隔离 cognee/modules/users/models/User.py:1-20。
  • 多租户隔离：通过 DatasetDatabase 存储每个数据集的向量数据库和图数据库连接字符串 cognee/modules/users/models/DatasetDatabase.py:7-40。
  • 管线执行：追踪后台任务的状态和历史 cognee/modules/pipelines/operations/run_tasks.py:74-76。

来源： cognee/modules/data/models/Data.py:12-48、cognee/modules/users/models/DatasetDatabase.py:7-40、cognee/modules/data/models/DatasetData.py:1-15

关系型数据库层架构

Cognee 使用 SQLAlchemyAdapter 提供面向 SQLite 或 PostgreSQL 的异步接口。引擎的选择由 create_relational_engine 控制，该函数负责构建连接字符串，包括对凭证中特殊字符的转义处理 cognee/infrastructure/databases/relational/create_relational_engine.py:10-79。

数据库引擎初始化

SQLAlchemyAdapter 处理数据库连接的生命周期。对于 SQLite，它支持可选的 S3 同步功能，将数据库拉取到本地临时文件进行处理，并将更新推送回云存储 cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:62-111。

Cognee · 数据库引擎初始化 · 图 1
Cognee · 数据库引擎初始化 · 图 1

来源： cognee/infrastructure/databases/relational/sqlalchemy/SqlAlchemyAdapter.py:27-104、cognee/infrastructure/databases/relational/create_relational_engine.py:10-79、cognee/infrastructure/databases/relational/config.py:12-82

核心模式模型

用户模型

User 模型代表系统主体。它作为数据集的所有者，用于实施访问控制。

  • id：UUID 主键。
  • tenant_id：用于多租户隔离的 UUID cognee/modules/users/models/User.py:1-20。
数据模型

表示一个特定的信息单元及其处理状态。

  • id：UUID 主键 cognee/modules/data/models/Data.py:15。
  • content_hash：用于入库过程中的去重 cognee/modules/data/models/Data.py:27。
  • pipeline_status：一个 JSON 字段，用于追踪任务进度（例如"片段切分"、"摘要生成"）cognee/modules/data/models/Data.py:34。
数据集数据库模型

该模型是 Cognee 多租户架构的核心。它存储外部数据库的隔离连接参数。

  • vector_database_provider：（例如"pgvector"、"lancedb"）cognee/modules/users/models/DatasetDatabase.py:18。
  • vector_database_connection_info：包含主机、端口以及提供方特定密钥的 JSON 字段 cognee/modules/users/models/DatasetDatabase.py:35。

来源： cognee/modules/data/models/Data.py:12-62、cognee/modules/users/models/DatasetDatabase.py:7-40、cognee/modules/users/models/User.py:1-20

数据库迁移

Cognee 使用 Alembic 管理关系型数据的模式演进，并使用自定义的适配器特定逻辑管理向量数据库。

  1. 关系型迁移：通过 run_migrations() 执行，该函数使用 sys.executable 调用 alembic upgrade head，以确保与虚拟环境的兼容性 cognee/run_migrations.py:19-61。
  2. 向量迁移：通过 run_vector_migrations() 执行。如果 backend_access_control_enabled 为 true，则会遍历所有 DatasetDatabase 条目，并为每个隔离的向量存储执行迁移 cognee/run_migrations.py:63-160。

来源： cognee/run_migrations.py:19-171、cognee/tests/unit/test_run_migrations.py:12-40

多租户连接处理

当 backend_access_control_enabled 启用时，Cognee 会动态解析数据库连接。对于像 pgvector 这样的提供方，PGVectorDatasetDatabaseHandler 管理着与 Cognee 数据集对应的物理 Postgres 数据库的创建和删除 cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:21-58。

Cognee · 多租户连接处理 · 图 2
Cognee · 多租户连接处理 · 图 2

来源： cognee/infrastructure/databases/vector/pgvector/PGVectorDatasetDatabaseHandler.py:15-94、cognee/infrastructure/databases/vector/pgvector/create_db_and_tables.py:20-64、cognee/infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py:17-36

配置管理

RelationalConfig 类使用 Pydantic 管理数据库设置。它通过 JSON 编码的环境变量支持复杂配置：

  • DATABASE_CONNECT_ARGS：解析为字典并传递给 SQLAlchemy 引擎（例如用于 SSL 设置）cognee/infrastructure/databases/relational/config.py:37-47。
  • POOL_ARGS：配置连接池（池大小、溢出、回收）cognee/infrastructure/databases/relational/config.py:49-57。

来源： cognee/infrastructure/databases/relational/config.py:12-82、cognee/infrastructure/databases/relational/create_relational_engine.py:45-79