docs(api): graph schema cloning and distinguish from config

content/cn/docs/clients/restful-api/graphs.md

@@ -105,28 +105,39 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_
 
 #### 6.1.4 克隆一个图
 
-##### Params
+HugeGraph 提供两种图克隆方式：
+1. **模式一：仅配置克隆（Configuration Clone）**：仅复制源图的配置信息，不复制 Schema、顶点或边数据。
+2. **模式二：Schema 克隆（Schema Clone，Server API 0.73+）**：在同一图空间内复制源图配置及属性键、顶点标签和索引标签，不复制顶点与边数据。
 
-**路径参数说明：**
+##### 模式一：仅配置克隆
 
-- graphspace: 图空间名称
-- graph: 要创建的新图名称
+通过图创建端点配合查询参数 `clone_graph_name` 复制源图配置。
 
-**请求参数说明：**
+> [!NOTE]
+> 在 PD 模式下，若源图配置了 `schema.init_template`，克隆出的新图也会继承该配置并基于模板初始化 Schema。
 
-- clone_graph_name: 已有图的名称；从已有的图来克隆，用户可选择传递配置文件，传递时将替换已有图中的配置；
+###### Params
 
-##### Method & Url
+**路径参数：**
 
-```text
+- `graphspace`: 图空间名称
+- `graph`: 要创建的新图名称
+
+**查询参数：**
+
+- `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",
@@ -137,24 +148,79 @@ 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 克隆（Server API 0.73+）
+
+自 HugeGraph 1.8.0（Server REST API 0.73+）起提供同步的 Schema 克隆接口。该接口在同一图空间内创建新图，并复制源图的所有属性键、顶点标签及相关索引，但不复制顶点与边数据。复制时会自动清空 `schema.init_template`，以准确复制源图当时的实际 Schema。
+
+克隆期间请保持源图 Schema 不变。开启鉴权时，调用该接口需要图空间管理权限（Space Admin）。
+
+> [!CAUTION]
+> **暂不支持包含边标签（EdgeLabel）的源图**：由于部分后端存储无法可靠还原边标签的继承层级，若源图包含任何边标签，服务端将在创建目标图前直接拦截拒绝；克隆过程中若有新增边标签也会报错中断。
+
+> [!WARNING]
+> **非原子操作与残留清理**：Schema 复制不是原子事务。若在创建目标图后复制 Schema 元素失败，新图可能处于部分初始化的状态且对外可见。服务端不会自动回滚或删除已建的图；遇到失败需排查并显式调用删除接口清理该目标图后再重试。
+
+###### Params
+
+**路径参数：**
+
+- `graphspace`: 图空间名称
+- `graph`: 要创建的目标图名称
+
+**查询参数：**
+
+- `source`: 同一图空间内的源图名称（必填）
+
+###### Method & Url
+
+```http
+POST http://localhost:8080/graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=vertices_only
+```
+
+###### Request Body (可选)
+
+仅支持通过 JSON 指定 `nickname`（可选）：
+
+```json
+{
+  "nickname": "Schema copy"
+}
+```
+
+###### Response Status
+
+```text
+201
+```
+
+###### Response Body
+
+```json
+{
+  "name": "schema_copy",
+  "nickname": "Schema copy",
+  "backend": "rocksdb"
 }
 ```
 

content/en/docs/clients/restful-api/graphs.md

@@ -105,28 +105,41 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_
 
 #### 6.1.4 Clone graph
 
-##### Params
+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.
 
-**Path parameters**
+##### Mode 1: Configuration clone
 
-- graphspace: Graphspace name
-- graph: Name of the new graph to create
+This endpoint clones graph configuration using the `clone_graph_name` query parameter.
 
-**Query 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.
 
-- 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
+###### Params
 
-##### Method & Url
+**Path parameters:**
 
-```text
+- `graphspace`: Graphspace name
+- `graph`: Name of the new graph to create
+
+**Query parameters:**
+
+- `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",
@@ -137,24 +150,84 @@ 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": ""
+}
+```
+
+##### 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.
+
+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.
+
+> [!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
+- `graph`: Name of the target graph to create
+
+**Query parameters:**
+
+- `source`: Name of the source graph in the same graphspace (required)
+
+###### Method & Url
+
+```http
+POST http://localhost:8080/graphspaces/DEFAULT/graphs/schema_copy/schema-clone?source=vertices_only
+```
+
+###### Request Body [Optional]
+
+Optionally specify a `nickname` in JSON:
+
+```json
+{
+  "nickname": "Schema copy"
+}
+```
+
+###### Response Status
+
+```text
+201
+```
+
+###### Response Body
+
+```json
+{
+  "name": "schema_copy",
+  "nickname": "Schema copy",
+  "backend": "rocksdb"
 }
 ```