From d9d3d064910cb20548308dd7d139c1e0c7996091 Mon Sep 17 00:00:00 2001 From: orion Date: Fri, 30 Oct 2026 17:33:13 +0000 Subject: [PATCH 1/5] docs: describe graph schema clone contract --- content/cn/docs/clients/restful-api/graphs.md | 20 ++++++++++++++++++ content/en/docs/clients/restful-api/graphs.md | 21 +++++++++++++++++++ 2 files changed, 41 insertions(+) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 5decfc0f9e..60b88ce638 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -105,6 +105,9 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_ #### 6.1.4 克隆一个图 +该接口仅复制源图的配置，不复制 Schema、顶点或边。`clone_graph_name` 是查询参数，不能放在 JSON 请求体中。 + + ##### Params **路径参数说明：** @@ -158,6 +161,23 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_nam } ``` +##### 复制图的 Schema + +包含 [Schema 克隆变更](https://github.com/hugegraph/hugegraph/pull/361)的 Server 构建还提供独立的同步接口。 +该接口在同一图空间创建新图并复制属性键、顶点标签、边标签和索引，不复制图数据。复制期间请保持源 Schema 不变。 +开启鉴权时需要图空间管理权限。 + +```http +POST /graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=hugegraph +Content-Type: application/json + +{"nickname":"Schema copy"} +``` + +`nickname` 可省略。201 响应包含新图的 `name`、`nickname` 和 `backend`，表示 Schema 复制已完成。 +操作失败可能留下部分创建的目标图；重试前请检查并显式删除目标图。旧版 Server 不支持此接口， +不能将 `clone_graph_name` 的 201 响应当作 Schema 复制成功。 + #### 6.1.5 创建一个图 ##### Params diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 6a5fca65df..3d51a285a2 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -105,6 +105,10 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_ #### 6.1.4 Clone graph +This endpoint copies the source graph configuration only. It does not copy schema, vertices, or edges. +`clone_graph_name` is a query parameter, not a JSON field. + + ##### Params **Path parameters** @@ -158,6 +162,23 @@ Clone a `non-auth` mode graph (set `Content-Type: application/json`) } ``` +##### Copy a graph schema + +Server builds containing [the schema-clone change](https://github.com/hugegraph/hugegraph/pull/361) also provide a separate synchronous API. +It creates a new graph in the same graph space and copies property keys, vertex labels, edge labels, and indexes; it does not copy graph data. +Keep the source schema unchanged while copying. Authentication, when enabled, requires graph-space administrator permission. + +```http +POST /graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=hugegraph +Content-Type: application/json + +{"nickname":"Schema copy"} +``` + +`nickname` is optional. A 201 response contains the new graph's `name`, `nickname`, and `backend`, and indicates schema copying completed. +A failed operation can leave a partially created target; inspect it and remove it explicitly before retrying. +Older Servers do not provide this API. Do not substitute `clone_graph_name` and treat its 201 as a successful schema copy. + #### 6.1.5 Create graph ##### Params From d52ec0e4d9a415a5b57aac21ca03ca42cd9588c4 Mon Sep 17 00:00:00 2001 From: orion Date: Sat, 31 Oct 2026 03:55:48 +0000 Subject: [PATCH 2/5] docs: specify schema clone API version --- content/cn/docs/clients/restful-api/graphs.md | 3 ++- content/en/docs/clients/restful-api/graphs.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 60b88ce638..f80ea525ec 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -163,7 +163,8 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_nam ##### 复制图的 Schema -包含 [Schema 克隆变更](https://github.com/hugegraph/hugegraph/pull/361)的 Server 构建还提供独立的同步接口。 +包含[拟议的 Schema 克隆变更](https://github.com/hugegraph/hugegraph/pull/361)的 Server 构建提供独立的同步接口。 +客户端应要求 `GET /versions` 返回的 `versions.api` 不低于 `0.73.0.0`；该变更尚未发布。 该接口在同一图空间创建新图并复制属性键、顶点标签、边标签和索引，不复制图数据。复制期间请保持源 Schema 不变。 开启鉴权时需要图空间管理权限。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 3d51a285a2..850de2b3a5 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -164,7 +164,8 @@ Clone a `non-auth` mode graph (set `Content-Type: application/json`) ##### Copy a graph schema -Server builds containing [the schema-clone change](https://github.com/hugegraph/hugegraph/pull/361) also provide a separate synchronous API. +Server builds containing [the proposed schema-clone change](https://github.com/hugegraph/hugegraph/pull/361) provide a separate synchronous API. +Clients should require `versions.api` of `0.73.0.0` or later from `GET /versions`; this change has not yet been released. It creates a new graph in the same graph space and copies property keys, vertex labels, edge labels, and indexes; it does not copy graph data. Keep the source schema unchanged while copying. Authentication, when enabled, requires graph-space administrator permission. From 7b15acfef3cdc10ae1bbe63798a84953a10a1735 Mon Sep 17 00:00:00 2001 From: orion Date: Sat, 31 Oct 2026 04:06:30 +0000 Subject: [PATCH 3/5] docs: clarify schema clone edge label restriction --- content/cn/docs/clients/restful-api/graphs.md | 7 ++++--- content/en/docs/clients/restful-api/graphs.md | 8 +++++--- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index f80ea525ec..e4248ff6d2 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -165,17 +165,18 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_nam 包含[拟议的 Schema 克隆变更](https://github.com/hugegraph/hugegraph/pull/361)的 Server 构建提供独立的同步接口。 客户端应要求 `GET /versions` 返回的 `versions.api` 不低于 `0.73.0.0`；该变更尚未发布。 -该接口在同一图空间创建新图并复制属性键、顶点标签、边标签和索引，不复制图数据。复制期间请保持源 Schema 不变。 +该接口在同一图空间创建新图并复制属性键、顶点标签及其索引，不复制图数据。 +目前，源图只要包含边标签，就会在创建目标图之前被拒绝，因为部分存储无法可靠还原边标签层级。复制期间请保持源 Schema 不变。 开启鉴权时需要图空间管理权限。 ```http -POST /graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=hugegraph +POST /graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=vertices_only Content-Type: application/json {"nickname":"Schema copy"} ``` -`nickname` 可省略。201 响应包含新图的 `name`、`nickname` 和 `backend`，表示 Schema 复制已完成。 +示例假设 `vertices_only` 没有边标签。`nickname` 可省略。201 响应包含新图的 `name`、`nickname` 和 `backend`，表示 Schema 复制已完成。 操作失败可能留下部分创建的目标图；重试前请检查并显式删除目标图。旧版 Server 不支持此接口， 不能将 `clone_graph_name` 的 201 响应当作 Schema 复制成功。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 850de2b3a5..96d9ad3232 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -166,17 +166,19 @@ Clone a `non-auth` mode graph (set `Content-Type: application/json`) Server builds containing [the proposed schema-clone change](https://github.com/hugegraph/hugegraph/pull/361) provide a separate synchronous API. Clients should require `versions.api` of `0.73.0.0` or later from `GET /versions`; this change has not yet been released. -It creates a new graph in the same graph space and copies property keys, vertex labels, edge labels, and indexes; it does not copy graph data. +It creates a new graph in the same graph space and copies property keys, vertex labels, and their indexes; it does not copy graph data. +For now, any source with an edge label is rejected before the target is created because some stores cannot reliably recover edge-label hierarchy. Keep the source schema unchanged while copying. Authentication, when enabled, requires graph-space administrator permission. ```http -POST /graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=hugegraph +POST /graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=vertices_only Content-Type: application/json {"nickname":"Schema copy"} ``` -`nickname` is optional. A 201 response contains the new graph's `name`, `nickname`, and `backend`, and indicates schema copying completed. +The example assumes `vertices_only` has no edge labels. `nickname` is optional. +A 201 response contains the new graph's `name`, `nickname`, and `backend`, and indicates schema copying completed. A failed operation can leave a partially created target; inspect it and remove it explicitly before retrying. Older Servers do not provide this API. Do not substitute `clone_graph_name` and treat its 201 as a successful schema copy. From be321e03cf2d2af0aec18f36036003ca229bae98 Mon Sep 17 00:00:00 2001 From: dark Date: Sun, 1 Nov 2026 17:36:48 +0800 Subject: [PATCH 4/5] docs(api): document graph schema cloning and distinguish from configuration cloning --- content/cn/docs/clients/restful-api/graphs.md | 114 +++++++++++------ content/en/docs/clients/restful-api/graphs.md | 116 ++++++++++++------ 2 files changed, 158 insertions(+), 72 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index e4248ff6d2..2ff9e7053b 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -105,31 +105,39 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_ #### 6.1.4 克隆一个图 -该接口仅复制源图的配置，不复制 Schema、顶点或边。`clone_graph_name` 是查询参数，不能放在 JSON 请求体中。 +HugeGraph 提供两种图克隆方式： +1. **模式一：仅配置克隆（Configuration Clone）**：复制源图配置，不复制 Schema、顶点或边数据。 +2. **模式二：Schema 克隆（Schema Clone，Server API 0.73+）**：在同一图空间内复制源图配置及属性键、顶点标签和索引标签，不复制顶点与边数据。 +##### 模式一：仅配置克隆 -##### Params +通过图创建端点配合查询参数 `clone_graph_name` 复制源图配置。 -**路径参数说明：** +> [!NOTE] +> 在 PD 模式下，若源图配置了 `schema.init_template`，克隆出的新图也会继承该配置并基于模版初始化初始 Schema。 -- graphspace: 图空间名称 -- graph: 要创建的新图名称 +###### Params -**请求参数说明：** +**路径参数：** -- clone_graph_name: 已有图的名称；从已有的图来克隆，用户可选择传递配置文件，传递时将替换已有图中的配置； +- `graphspace`: 图空间名称 +- `graph`: 要创建的新图名称 -##### Method & Url +**查询参数：** -```text +- `clone_graph_name`: 源图名称。注意必须作为 Query 参数传入，不能放在请求体 JSON 中。 + +###### Method & Url + +```http POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_name=hugegraph ``` -##### Request Body (可选) +###### Request Body (可选) -克隆一个非鉴权模式的图（设置 `Content-Type: application/json`） +可选择传入 JSON 配置覆盖源图配置（例如自定义存储目录等）： -```javascript +```json { "gremlin.graph": "org.apache.hugegraph.HugeFactory", "backend": "rocksdb", @@ -140,45 +148,81 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_nam } ``` -> Note: -> 1. Rocksdb 存储路径不能与现有图相同（需使用不同的目录） -> 2. 如需开启新图的权限系统，需替换设置 `gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy` +> [!NOTE] +> 1. RocksDB 存储路径不能与现有图冲突，需指定不同目录。 +> 2. 如需开启权限认证，需设置 `"gremlin.graph": "org.apache.hugegraph.auth.HugeFactoryAuthProxy"`。 -##### Response Status +###### Response Status -```javascript +```text 201 ``` -##### Response Body +###### Response Body -```javascript +```json { - "name": "cloneGraph", - "nickname": "cloneGraph", - "backend": "rocksdb", - "description": "" + "name": "cloneGraph", + "nickname": "cloneGraph", + "backend": "rocksdb", + "description": "" } ``` -##### 复制图的 Schema +##### 模式二：Schema 克隆（Server API 0.73+） + +自 HugeGraph 1.8.0（Server REST API 0.73+）起提供同步的 Schema 克隆接口。该接口在同一图空间内创建新图，并复制源图的所有属性键、顶点标签及相关索引，但不复制顶点与边数据。复制时会自动清空 `schema.init_template`，以准确复制源图当时的实际 Schema。 + +开启鉴权时，调用该接口需要图空间管理权限（Space Admin）。 + +> [!CAUTION] +> **暂不支持包含边标签（EdgeLabel）的源图**：由于部分后端存储无法可靠还原边标签的继承层级，若源图包含任何边标签，服务端将在创建目标图前直接拦截拒绝；克隆过程中也会动态校验源图是否有新加入的边标签。 -包含[拟议的 Schema 克隆变更](https://github.com/hugegraph/hugegraph/pull/361)的 Server 构建提供独立的同步接口。 -客户端应要求 `GET /versions` 返回的 `versions.api` 不低于 `0.73.0.0`；该变更尚未发布。 -该接口在同一图空间创建新图并复制属性键、顶点标签及其索引，不复制图数据。 -目前，源图只要包含边标签，就会在创建目标图之前被拒绝，因为部分存储无法可靠还原边标签层级。复制期间请保持源 Schema 不变。 -开启鉴权时需要图空间管理权限。 +> [!WARNING] +> **非原子操作与残留清理**：Schema 复制不是原子事务。若在创建目标图后复制 Schema 元素失败，新图可能处于部分初始化的状态且对外可见。服务端不会自动回滚或删除已建的图；遇到失败需排查并显式调用删除接口清理该目标图后再重试。 + +###### Params + +**路径参数：** + +- `graphspace`: 图空间名称 +- `name`: 要创建的目标图名称 + +**查询参数：** + +- `source`: 同一图空间内的源图名称（必填） + +###### Method & Url ```http -POST /graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=vertices_only -Content-Type: application/json +POST http://localhost:8080/graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=vertices_only +``` + +###### Request Body (可选) -{"nickname":"Schema copy"} +仅支持通过 JSON 指定 `nickname`（可选）： + +```json +{ + "nickname": "Schema copy" +} +``` + +###### Response Status + +```text +201 ``` -示例假设 `vertices_only` 没有边标签。`nickname` 可省略。201 响应包含新图的 `name`、`nickname` 和 `backend`，表示 Schema 复制已完成。 -操作失败可能留下部分创建的目标图；重试前请检查并显式删除目标图。旧版 Server 不支持此接口， -不能将 `clone_graph_name` 的 201 响应当作 Schema 复制成功。 +###### Response Body + +```json +{ + "name": "schema_copy", + "nickname": "Schema copy", + "backend": "rocksdb" +} +``` #### 6.1.5 创建一个图 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 96d9ad3232..e3f45409d1 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -105,32 +105,39 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_ #### 6.1.4 Clone graph -This endpoint copies the source graph configuration only. It does not copy schema, vertices, or edges. -`clone_graph_name` is a query parameter, not a JSON field. +HugeGraph supports two graph cloning modes: +1. **Mode 1: Configuration clone**: Copies only the source graph configuration, without copying schema, vertices, or edges. +2. **Mode 2: Schema clone (Server API 0.73+)**: Copies the configuration as well as PropertyKeys, VertexLabels, and IndexLabels within the same graph space, without copying graph vertices or edges. +##### Mode 1: Configuration clone -##### Params +This endpoint clones graph configuration using the `clone_graph_name` query parameter. -**Path parameters** +> [!NOTE] +> In PD mode, if the source graph is configured with `schema.init_template`, the cloned graph inherits that template setting and initializes its schema accordingly. -- graphspace: Graphspace name -- graph: Name of the new graph to create +###### Params -**Query parameters** +**Path parameters:** -- clone_graph_name: name of an existed graph. To clone from an existing graph, the user can choose to transfer the configuration file, which will replace the configuration in the existing graph +- `graphspace`: Graphspace name +- `graph`: Name of the new graph to create -##### Method & Url +**Query parameters:** -```text +- `clone_graph_name`: Name of the source graph. Note that this must be passed as a query parameter, not inside the JSON body. + +###### Method & Url + +```http POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_name=hugegraph ``` -##### Request Body [Optional] +###### Request Body [Optional] -Clone a `non-auth` mode graph (set `Content-Type: application/json`) +Optionally pass configuration overrides in JSON format: -```javascript +```json { "gremlin.graph": "org.apache.hugegraph.HugeFactory", "backend": "rocksdb", @@ -141,46 +148,81 @@ Clone a `non-auth` mode graph (set `Content-Type: application/json`) } ``` -> Note: -> 1. The data/wal_path can't be the same as the existing graph (use separate directories) -> 2. Replace "gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy" to enable auth mode +> [!NOTE] +> 1. RocksDB data/wal paths cannot conflict with existing graphs; use separate directories. +> 2. Set `"gremlin.graph": "org.apache.hugegraph.auth.HugeFactoryAuthProxy"` to enable auth mode on the new graph. -##### Response Status +###### Response Status -```javascript +```text 201 ``` -##### Response Body +###### Response Body -```javascript +```json { - "name": "cloneGraph", - "nickname": "cloneGraph", - "backend": "rocksdb", - "description": "" + "name": "cloneGraph", + "nickname": "cloneGraph", + "backend": "rocksdb", + "description": "" } ``` -##### Copy a graph schema +##### Mode 2: Schema clone (Server API 0.73+) + +Starting from HugeGraph 1.8.0 (Server REST API 0.73+), a dedicated synchronous schema cloning API is provided. It creates a new graph in the same graph space and copies all property keys, vertex labels, and their index labels, without copying vertex or edge data. During cloning, `schema.init_template` is automatically cleared to ensure the target reflects the actual source schema rather than re-instantiating the template. + +When authentication is enabled, graph space administrator permission (`space`) is required. + +> [!CAUTION] +> **EdgeLabel restriction**: Because certain storage backends cannot reliably reconstruct edge label hierarchy metadata, sources with any edge labels are rejected before creating the target graph. The server also checks dynamically during copying that no edge labels were added. -Server builds containing [the proposed schema-clone change](https://github.com/hugegraph/hugegraph/pull/361) provide a separate synchronous API. -Clients should require `versions.api` of `0.73.0.0` or later from `GET /versions`; this change has not yet been released. -It creates a new graph in the same graph space and copies property keys, vertex labels, and their indexes; it does not copy graph data. -For now, any source with an edge label is rejected before the target is created because some stores cannot reliably recover edge-label hierarchy. -Keep the source schema unchanged while copying. Authentication, when enabled, requires graph-space administrator permission. +> [!WARNING] +> **Non-atomic operation and failure cleanup**: Schema copying is not an atomic transaction. If copying schema elements fails after the target graph has been created, the graph may remain visible with partial schema. The server does not automatically roll back or drop the target graph. Inspect and delete the incomplete target graph before retrying. + +###### Params + +**Path parameters:** + +- `graphspace`: Graphspace name +- `name`: Name of the target graph to create + +**Query parameters:** + +- `source`: Name of the source graph in the same graphspace (required) + +###### Method & Url ```http -POST /graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=vertices_only -Content-Type: application/json +POST http://localhost:8080/graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=vertices_only +``` + +###### Request Body [Optional] -{"nickname":"Schema copy"} +Optionally specify a `nickname` in JSON: + +```json +{ + "nickname": "Schema copy" +} +``` + +###### Response Status + +```text +201 ``` -The example assumes `vertices_only` has no edge labels. `nickname` is optional. -A 201 response contains the new graph's `name`, `nickname`, and `backend`, and indicates schema copying completed. -A failed operation can leave a partially created target; inspect it and remove it explicitly before retrying. -Older Servers do not provide this API. Do not substitute `clone_graph_name` and treat its 201 as a successful schema copy. +###### Response Body + +```json +{ + "name": "schema_copy", + "nickname": "Schema copy", + "backend": "rocksdb" +} +``` #### 6.1.5 Create graph From 72963f4b510f7dc3624ae6b23a64a342dee900b6 Mon Sep 17 00:00:00 2001 From: dark Date: Sun, 1 Nov 2026 17:43:50 +0800 Subject: [PATCH 5/5] docs(api): polish schema clone phrasing, wrap lines, and align parameter naming --- content/cn/docs/clients/restful-api/graphs.md | 10 ++++----- content/en/docs/clients/restful-api/graphs.md | 21 ++++++++++++------- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 2ff9e7053b..d9c0c841b5 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -106,7 +106,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_ #### 6.1.4 克隆一个图 HugeGraph 提供两种图克隆方式： -1. **模式一：仅配置克隆（Configuration Clone）**：复制源图配置，不复制 Schema、顶点或边数据。 +1. **模式一：仅配置克隆（Configuration Clone）**：仅复制源图的配置信息，不复制 Schema、顶点或边数据。 2. **模式二：Schema 克隆（Schema Clone，Server API 0.73+）**：在同一图空间内复制源图配置及属性键、顶点标签和索引标签，不复制顶点与边数据。 ##### 模式一：仅配置克隆 @@ -114,7 +114,7 @@ HugeGraph 提供两种图克隆方式： 通过图创建端点配合查询参数 `clone_graph_name` 复制源图配置。 > [!NOTE] -> 在 PD 模式下，若源图配置了 `schema.init_template`，克隆出的新图也会继承该配置并基于模版初始化初始 Schema。 +> 在 PD 模式下，若源图配置了 `schema.init_template`，克隆出的新图也会继承该配置并基于模板初始化 Schema。 ###### Params @@ -173,10 +173,10 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_nam 自 HugeGraph 1.8.0（Server REST API 0.73+）起提供同步的 Schema 克隆接口。该接口在同一图空间内创建新图，并复制源图的所有属性键、顶点标签及相关索引，但不复制顶点与边数据。复制时会自动清空 `schema.init_template`，以准确复制源图当时的实际 Schema。 -开启鉴权时，调用该接口需要图空间管理权限（Space Admin）。 +克隆期间请保持源图 Schema 不变。开启鉴权时，调用该接口需要图空间管理权限（Space Admin）。 > [!CAUTION] -> **暂不支持包含边标签（EdgeLabel）的源图**：由于部分后端存储无法可靠还原边标签的继承层级，若源图包含任何边标签，服务端将在创建目标图前直接拦截拒绝；克隆过程中也会动态校验源图是否有新加入的边标签。 +> **暂不支持包含边标签（EdgeLabel）的源图**：由于部分后端存储无法可靠还原边标签的继承层级，若源图包含任何边标签，服务端将在创建目标图前直接拦截拒绝；克隆过程中若有新增边标签也会报错中断。 > [!WARNING] > **非原子操作与残留清理**：Schema 复制不是原子事务。若在创建目标图后复制 Schema 元素失败，新图可能处于部分初始化的状态且对外可见。服务端不会自动回滚或删除已建的图；遇到失败需排查并显式调用删除接口清理该目标图后再重试。 @@ -186,7 +186,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_nam **路径参数：** - `graphspace`: 图空间名称 -- `name`: 要创建的目标图名称 +- `graph`: 要创建的目标图名称 **查询参数：** diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index e3f45409d1..2f0ce6b2a7 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -107,14 +107,16 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_ HugeGraph supports two graph cloning modes: 1. **Mode 1: Configuration clone**: Copies only the source graph configuration, without copying schema, vertices, or edges. -2. **Mode 2: Schema clone (Server API 0.73+)**: Copies the configuration as well as PropertyKeys, VertexLabels, and IndexLabels within the same graph space, without copying graph vertices or edges. +2. **Mode 2: Schema clone (Server API 0.73+)**: Copies the configuration as well as PropertyKeys, VertexLabels, and IndexLabels within the same graph space, + without copying graph vertices or edges. ##### Mode 1: Configuration clone This endpoint clones graph configuration using the `clone_graph_name` query parameter. > [!NOTE] -> In PD mode, if the source graph is configured with `schema.init_template`, the cloned graph inherits that template setting and initializes its schema accordingly. +> In PD mode, if the source graph is configured with `schema.init_template`, the cloned graph inherits that template setting and initializes its schema +> accordingly. ###### Params @@ -171,22 +173,27 @@ Optionally pass configuration overrides in JSON format: ##### Mode 2: Schema clone (Server API 0.73+) -Starting from HugeGraph 1.8.0 (Server REST API 0.73+), a dedicated synchronous schema cloning API is provided. It creates a new graph in the same graph space and copies all property keys, vertex labels, and their index labels, without copying vertex or edge data. During cloning, `schema.init_template` is automatically cleared to ensure the target reflects the actual source schema rather than re-instantiating the template. +Starting from HugeGraph 1.8.0 (Server REST API 0.73+), a dedicated synchronous schema cloning API is provided. It creates a new graph in the same graph space +and copies all property keys, vertex labels, and their index labels, without copying vertex or edge data. During cloning, `schema.init_template` is +automatically cleared to ensure the target reflects the actual source schema rather than re-instantiating the template. -When authentication is enabled, graph space administrator permission (`space`) is required. +Keep the source schema unchanged during copying. When authentication is enabled, graph space administrator permission (`space`) is required. > [!CAUTION] -> **EdgeLabel restriction**: Because certain storage backends cannot reliably reconstruct edge label hierarchy metadata, sources with any edge labels are rejected before creating the target graph. The server also checks dynamically during copying that no edge labels were added. +> **EdgeLabel restriction**: Because certain storage backends cannot reliably reconstruct edge label hierarchy metadata, sources with any edge labels are +> rejected before creating the target graph. The server also checks dynamically during copying that no edge labels were added. > [!WARNING] -> **Non-atomic operation and failure cleanup**: Schema copying is not an atomic transaction. If copying schema elements fails after the target graph has been created, the graph may remain visible with partial schema. The server does not automatically roll back or drop the target graph. Inspect and delete the incomplete target graph before retrying. +> **Non-atomic operation and failure cleanup**: Schema copying is not an atomic transaction. If copying schema elements fails after the target graph has been +> created, the graph may remain visible with partial schema. The server does not automatically roll back or drop the target graph. Inspect and delete the +> incomplete target graph before retrying. ###### Params **Path parameters:** - `graphspace`: Graphspace name -- `name`: Name of the target graph to create +- `graph`: Name of the target graph to create **Query parameters:**