#个人与项目数据集
工作台通过 /api/personal-datasets 管理个人数据，通过 /api/projects/{project_id}/datasets 管理项目数据。Backend 保存目录、原始文件及归属信息，Graph Engine 管理构图状态和图版本。数据集 ID 以接口返回值为准，不能根据文件名推测；个人数据集与项目内的副本也有各自独立的 ID。
| 操作 | 请求 |
|---|---|
| 个人上传 | POST /api/personal-datasets — multipart/form-data: file，或 files + csv_schema |
| 项目上传 | POST /api/projects/{project_id}/datasets — multipart/form-data: file，或 files + csv_schema |
| 重命名 | PATCH /api/personal-datasets/{dataset_id} — { "name": "orders" } |
| 选择会话数据集 | PATCH /api/sessions/{session_id}/dataset — { "active_dataset_id": "..." } |
#上传格式与用途
| 内容 | 入口与处理 |
|---|---|
| SQL / CSV / TXT 源数据 | 构图工作台接收 .sql、.csv、.txt。UTF-8 文本可带 BOM；.sql 也可保存受支持的 SQLite 数据库镜像。上传后需构图。 |
| CSV 表组 | 一次选择一个或多个 CSV，检查表名、表头和键定义。上传 files + csv_schema，保存为同一数据集；多文件请求只允许 CSV。 |
| 已有图文件 | 数据集/会话导入还有 .json、.npz、.pt、.tsv、.edgelist、.dat 等入口；实际结构必须符合对应加载器要求。后缀本身不保证文件可加载，构图工作台也不接收所有这些格式。 |
| 单图与图分类 | .pt 等文件须按内容区分单图和多图分类数据。分类数据需要图集合、标签和划分；加载单图不会自动得到这些训练条件。 |
SQL 构图使用受支持的 SQLite DDL 与字面值 INSERT，不是 MySQL/PostgreSQL 任意 dump 兼容层，也不连接在线数据库。CSV 中数值外观的单元格仍是字符串；TXT 的自动识别、逐行记录和语义关系抽取是不同模式。先核对数据内容和用途，再选择入口。
#从上传到分析
- 上传 CSV、TXT 或 SQL 后，目录状态为 source_ready，构图状态为 not_built；这一步保存源文件，不代表图已生成。
- 打开构图面板，先查看原始样本、表头和字段说明；多表 CSV 确认主外键，TXT 选择所需导入模式。
- 发起 construction/build，并持续检查状态。ready 后可查看实例图、类型结构和保存版本；失败时先依据错误消息和报告修正问题。
- 在会话中选择或加载构图结果，再核对当前图信息。保存构图和更新会话活动图是两个动作。
- 图算法、子图检索和可视化使用会话活动单图。图分类训练使用另行加载的多图数据及划分，不能拿单个构图结果替代完整训练数据。
curl -X PATCH http://localhost:21108/api/sessions/SESSION_ID/dataset \
-H "Content-Type: application/json" \
-d '{"active_dataset_id":"DATASET_ID"}'#把个人构图结果用于项目
项目可以导入当前用户已经完成构图的个人数据集。可选列表只包含目录状态和构图状态均为 ready 的个人数据；未构图、失败或其他用户的数据不在此列表中。导入会复制源文件和保存的图，生成独立项目数据集，不移动原始个人数据，也不在项目中直接引用个人数据集 ID。
GET /api/projects/{project_id}/constructed-datasets
POST /api/projects/{project_id}/datasets/import-constructed
Content-Type: application/json
{"source_dataset_id":"PERSONAL_DATASET_ID"}后续操作使用响应中的新 dataset_id。源文件、CSV 表组定义和构图结果随副本保存，imported_from 记录来源 ID 与修订。只有项目尚未设置默认数据集时，导入结果才自动成为默认数据集；这仍不等于已替换某个正在使用的会话活动图。需要分析该副本时，在相应项目会话中选择并加载它。
#数据状态与版本编号
| 对象 | 标识与含义 | 使用方式 |
|---|---|---|
| 源数据集 | dataset_id 由上传接口返回；源文件存在不代表已完成构图。 | 读取构图状态，确认是否需要首次构建。 |
| 保存的构图结果 | revision 标识数据集内保存的构图成果，用于编辑并发检查。 | 读取真实元素和 revision，再提交基于该版本的预览与修改。 |
| 会话活动图 | graph_version 标识当前会话内的图状态；加载保存结果后可生成独立的会话版本。 | 算法、检索缓存和可视化使用当前会话图，不能用数据集 revision 替代。 |
| 图分类数据集 | 绑定的是多张图及其划分；与会话活动单图分开保存。 | 训练读取分类数据；查看某个分子时再把那张图加载为活动单图。 |
| 执行代次 | generation 标识同一运行的执行阶段，用于取消、审批继续和结果发布。 | 它属于执行控制，不能作为图版本或构图修订号。 |
构图保存与会话加载是两个步骤。例如，数据集保存到 revision=3 后，会话仍可能保留此前加载的图。需要继续分析新版数据时，使用 load_constructed_graph 加载保存成果，再通过 get_graph_info 核对当前图。切换会话图也不会反向覆盖数据集；如需保存会话中的派生图，应显式调用相应的数据集保存接口。
两个客户端同时编辑同一构图结果时，都必须携带各自读取的 revision。一个客户端先提交后，另一个客户端的旧版本请求应按冲突处理：重新读取图、重新预览，再确认修改。预览只展示将发生的变化；重复发送旧预览并不能解决版本冲突。
#旧接口迁移
旧 /api/datasets、会话 load-dataset / save-dataset 仍保留兼容。它们面向 Registry，不能简单地把路径替换为 personal-datasets：两个目录的 ID 和加载、删除语义不同。旧个人构图路径是例外，其 construction 系列允许只替换路径前缀。
X-iGraph-API-Deprecated: true
X-iGraph-Migration-Guide: /api/dataset-api-migration客户端可直接调用 GET /api/dataset-api-migration 获取默认工作区的结构化迁移说明，无需登录或提供用户 ID。现有兼容声明没有安排删除日期；智能体的 list_datasets、load_dataset、save_as_dataset 工具继续维护。