# Datasets and graph revisions

Manage personal and project datasets, distinguish retained sources from saved constructions and active session graphs, and load data for analysis.

## Personal and project datasets

The workspace manages personal data through /api/personal-datasets and project data through /api/projects/{project_id}/datasets. Backend retains the catalog, original files, and ownership, while Graph Engine manages construction state and graph revisions. Use the dataset ID returned by the API, not a filename-derived ID. A personal dataset and its project copy have independent IDs.

| Operation | Request |
| --- | --- |
| Personal upload | POST /api/personal-datasets — multipart/form-data: file, or files + csv_schema |
| Project upload | POST /api/projects/{project_id}/datasets — multipart/form-data: file, or files + csv_schema |
| Rename | PATCH /api/personal-datasets/{dataset_id} — { "name": "orders" } |
| Select for a session | PATCH /api/sessions/{session_id}/dataset — { "active_dataset_id": "..." } |

## Upload formats and purposes

| Content | Input and handling |
| --- | --- |
| SQL / CSV / TXT sources | The construction workspace accepts .sql, .csv, and .txt. UTF-8 text may include a BOM, and .sql can contain a supported SQLite database image. Construction is required after upload. |
| CSV bundle | Select one or more CSV files and review table names, headers, and keys. Upload files + csv_schema to retain them as one dataset; multi-file requests allow CSV only. |
| Existing graph files | Dataset/session import also exposes formats including .json, .npz, .pt, .tsv, .edgelist, and .dat, subject to the relevant loader’s data format. An extension alone does not establish compatibility, and the construction workspace does not accept all these formats. |
| Single graph and graph classification | Files such as .pt must be interpreted according to whether they contain a single graph or graph-classification data. Classification needs a graph collection, labels, and splits; loading one graph does not supply those requirements. |

SQL construction supports a subset of SQLite DDL and literal INSERTs, not arbitrary MySQL/PostgreSQL dumps or live database connections. Numeric-looking CSV cells remain strings. TXT auto-detection, line records, and semantic relationship extraction are different modes. Choose the entry point based on the data and intended use.

- [Input parsing and relational semantics](/en/construction/#inputs)
- [Multi-table CSV definitions](/en/construction/#multi-table)

## From upload to analysis

- A new CSV, TXT, or SQL upload has catalog status source_ready and construction status not_built. It retains the source; it does not create a finished graph.
- Open the construction panel to inspect source samples, headers, and descriptions. Confirm keys for multi-table CSV and choose the intended TXT mode.
- Start construction/build and monitor status. Once ready, inspect the instance graph, type schema, and saved revision; on failure, correct the issue using the message and report.
- Select or load the construction result in a session and verify the current graph. Saving construction and updating an active session graph are separate actions.
- Algorithms, subgraph retrieval, and visualization use the active single graph. Graph classification uses separately loaded multi-graph data and splits; one constructed graph is not a substitute for that training dataset.

```bash
curl -X PATCH http://localhost:21108/api/sessions/SESSION_ID/dataset \
  -H "Content-Type: application/json" \
  -d '{"active_dataset_id":"DATASET_ID"}'
```

- [Source previews and description provenance](/en/construction/#source-preview)
- [Construction states and recovery](/en/construction/#lifecycle)
- [Workspace walkthrough](/en/workspace/)

## Reuse a personal construction in a project

A project can import a personal dataset already constructed by the current user. The selection includes only personal datasets whose catalog and construction states are both ready, excluding unbuilt, failed, or other users’ data. Import copies the retained source and saved graph into an independent project dataset; it does not move the personal data or directly bind its ID into the project.

```http
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"}
```

Use the new dataset_id returned by the response. The copy retains the source, CSV-bundle metadata, and constructed graph; imported_from records the source ID and revision. It becomes the project default only if no default is already set. This does not itself replace an active session graph. Select and load the copy in the appropriate project session for analysis.

## Data state and version identifiers

| Object | Identity and meaning | Usage |
| --- | --- | --- |
| Source dataset | Upload returns dataset_id; an existing source file does not establish a constructed graph. | Inspect construction state to decide whether an initial build is needed. |
| Saved construction | revision identifies a saved construction result and supports concurrent-edit checks. | Read actual elements and revision before previewing and committing edits against that base. |
| Active session graph | graph_version identifies graph state within a session; loading saved results can produce a separate session version. | Algorithms, retrieval caches, and visualization use the session graph; dataset revision is not a substitute. |
| Graph-classification dataset | Binds multiple graphs and their splits separately from the active single graph. | Training reads the classification data; load an individual molecule as the active graph for inspection. |
| Execution generation | generation identifies an execution phase within a run for cancellation, continuation, and publication. | It belongs to execution control, not graph versioning or construction revisions. |

Saving construction and loading a session graph are separate actions. After a dataset reaches revision=3, a session may still hold a previously loaded graph. Load the saved result with load_constructed_graph and verify it with get_graph_info before analyzing the update. Switching a session graph does not overwrite the dataset; persisting a derived session graph requires an explicit dataset-save operation.

Concurrent editors must supply the revision each read. If one commits first, the other handles its stale request as a conflict: reread the graph, preview again, and confirm the new edits. A preview describes prospective changes; resending the old preview does not resolve a version conflict.

## Legacy API migration

Legacy /api/datasets and session load-dataset / save-dataset endpoints remain compatible. They address the registry, so replacing their prefixes with personal-datasets is not a general migration: IDs and loading/deletion semantics differ. Legacy personal construction routes are aliases and do allow a prefix-only substitution.

```http
X-iGraph-API-Deprecated: true
X-iGraph-Migration-Guide: /api/dataset-api-migration
```

Clients can call GET /api/dataset-api-migration directly for structured migration information in the default workspace, without sign-in or a user ID. Existing compatibility declarations have no scheduled removal date; list_datasets, load_dataset, and save_as_dataset remain maintained.