This is an automated email from the ASF dual-hosted git repository.
zhangliang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 8a151d4d328 Add RAL docs for metadata import/export and storage nodes
export (#38206)
8a151d4d328 is described below
commit 8a151d4d328ce72b2c49771fd7b45cbaf687d16e
Author: ym0506 <[email protected]>
AuthorDate: Thu Feb 26 15:19:04 2026 +0900
Add RAL docs for metadata import/export and storage nodes export (#38206)
---
.../distsql/syntax/ral/export-metadata.cn.md | 57 ++++++++++++++++++++
.../distsql/syntax/ral/export-metadata.en.md | 57 ++++++++++++++++++++
.../distsql/syntax/ral/export-storage-nodes.cn.md | 62 ++++++++++++++++++++++
.../distsql/syntax/ral/export-storage-nodes.en.md | 62 ++++++++++++++++++++++
.../distsql/syntax/ral/import-metadata.cn.md | 53 ++++++++++++++++++
.../distsql/syntax/ral/import-metadata.en.md | 53 ++++++++++++++++++
6 files changed, 344 insertions(+)
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-metadata.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-metadata.cn.md
new file mode 100644
index 00000000000..f0ed6274e43
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-metadata.cn.md
@@ -0,0 +1,57 @@
++++
+title = "EXPORT METADATA"
+weight = 18
++++
+
+### 描述
+
+`EXPORT METADATA` 语法用于导出集群元数据，导出格式为 `JSON`。
+
+### 语法
+
+{{< tabs >}}
+{{% tab name="语法" %}}
+```sql
+ExportMetaData ::=
+ 'EXPORT' 'METADATA' ('TO' 'FILE' filePath)?
+
+filePath ::=
+ string
+```
+{{% /tab %}}
+{{% tab name="铁路图" %}}
+<iframe frameborder="0" name="diagram" id="diagram" width="100%"
height="100%"></iframe>
+{{% /tab %}}
+{{< /tabs >}}
+
+### 返回值说明
+
+| 列名 | 说明 |
+|--------------|----------------------------------------|
+| id | 当前计算节点 id |
+| create_time | 导出时间 |
+| cluster_info | 导出的元数据（或指定 `TO FILE` 时的成功提示） |
+
+### 补充说明
+
+- 未指定 `filePath` 时，`cluster_info` 列返回 Base64 编码的元数据内容；
+- 指定 `filePath` 时，会将元数据写入文件，`cluster_info` 列返回成功提示；
+- 若 `filePath` 的父目录不存在会自动创建，若文件已存在会被覆盖。
+
+### 示例
+
+```sql
+EXPORT METADATA;
+```
+
+```sql
+EXPORT METADATA TO FILE '/tmp/metadata.json';
+```
+
+### 保留字
+
+`EXPORT`、`METADATA`、`TO`、`FILE`
+
+### 相关链接
+
+- [保留字](/cn/user-manual/shardingsphere-proxy/distsql/syntax/reserved-word/)
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-metadata.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-metadata.en.md
new file mode 100644
index 00000000000..391c276fadc
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-metadata.en.md
@@ -0,0 +1,57 @@
++++
+title = "EXPORT METADATA"
+weight = 18
++++
+
+### Description
+
+The `EXPORT METADATA` syntax is used to export cluster metadata in `JSON`
format.
+
+### Syntax
+
+{{< tabs >}}
+{{% tab name="Grammar" %}}
+```sql
+ExportMetaData ::=
+ 'EXPORT' 'METADATA' ('TO' 'FILE' filePath)?
+
+filePath ::=
+ string
+```
+{{% /tab %}}
+{{% tab name="Railroad diagram" %}}
+<iframe frameborder="0" name="diagram" id="diagram" width="100%"
height="100%"></iframe>
+{{% /tab %}}
+{{< /tabs >}}
+
+### Return Value Description
+
+| Columns | Description |
+|--------------|--------------------------------------------------------------|
+| id | current compute node id |
+| create_time | export time |
+| cluster_info | exported metadata (or success message when `TO FILE` is set) |
+
+### Supplement
+
+- When `filePath` is not specified, the `cluster_info` column returns
Base64-encoded metadata;
+- When `filePath` is specified, metadata is written to file and `cluster_info`
returns a success message;
+- The parent directory of `filePath` will be created automatically if needed,
and existing file content will be overwritten.
+
+### Example
+
+```sql
+EXPORT METADATA;
+```
+
+```sql
+EXPORT METADATA TO FILE '/tmp/metadata.json';
+```
+
+### Reserved word
+
+`EXPORT`, `METADATA`, `TO`, `FILE`
+
+### Related links
+
+- [Reserved
word](/en/user-manual/shardingsphere-proxy/distsql/syntax/reserved-word/)
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-storage-nodes.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-storage-nodes.cn.md
new file mode 100644
index 00000000000..abe30e1d7d7
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-storage-nodes.cn.md
@@ -0,0 +1,62 @@
++++
+title = "EXPORT STORAGE NODES"
+weight = 20
++++
+
+### 描述
+
+`EXPORT STORAGE NODES` 语法用于导出存储节点配置，导出格式为 `JSON`。
+
+### 语法
+
+{{< tabs >}}
+{{% tab name="语法" %}}
+```sql
+ExportStorageNodes ::=
+ 'EXPORT' 'STORAGE' 'NODES' ('FROM' databaseName)? ('TO' 'FILE' filePath)?
+
+databaseName ::=
+ identifier
+
+filePath ::=
+ string
+```
+{{% /tab %}}
+{{% tab name="铁路图" %}}
+<iframe frameborder="0" name="diagram" id="diagram" width="100%"
height="100%"></iframe>
+{{% /tab %}}
+{{< /tabs >}}
+
+### 返回值说明
+
+| 列名 | 说明 |
+|---------------|-------------------------------------------|
+| id | 当前计算节点 id |
+| create_time | 导出时间 |
+| storage_nodes | 导出的存储节点 JSON（或指定 `TO FILE` 时的成功提示） |
+
+### 补充说明
+
+- 未指定 `databaseName` 时，导出所有逻辑库的存储节点；
+- 指定 `databaseName` 时，仅导出指定逻辑库的存储节点；
+- 指定的 `databaseName` 不存在时，导出会失败；
+- 指定 `filePath` 时，会将结果写入文件，若文件已存在会被覆盖；
+- 导出内容包含 `username`、`password` 等连接信息，请注意保护导出结果。
+
+### 示例
+
+```sql
+EXPORT STORAGE NODES;
+```
+
+```sql
+EXPORT STORAGE NODES FROM sharding_db TO FILE '/tmp/storage-nodes.json';
+```
+
+### 保留字
+
+`EXPORT`、`STORAGE`、`NODES`、`FROM`、`TO`、`FILE`
+
+### 相关链接
+
+- [保留字](/cn/user-manual/shardingsphere-proxy/distsql/syntax/reserved-word/)
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-storage-nodes.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-storage-nodes.en.md
new file mode 100644
index 00000000000..11c2b504838
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/export-storage-nodes.en.md
@@ -0,0 +1,62 @@
++++
+title = "EXPORT STORAGE NODES"
+weight = 20
++++
+
+### Description
+
+The `EXPORT STORAGE NODES` syntax is used to export storage node
configurations in `JSON` format.
+
+### Syntax
+
+{{< tabs >}}
+{{% tab name="Grammar" %}}
+```sql
+ExportStorageNodes ::=
+ 'EXPORT' 'STORAGE' 'NODES' ('FROM' databaseName)? ('TO' 'FILE' filePath)?
+
+databaseName ::=
+ identifier
+
+filePath ::=
+ string
+```
+{{% /tab %}}
+{{% tab name="Railroad diagram" %}}
+<iframe frameborder="0" name="diagram" id="diagram" width="100%"
height="100%"></iframe>
+{{% /tab %}}
+{{< /tabs >}}
+
+### Return Value Description
+
+| Columns | Description
|
+|---------------|---------------------------------------------------------------|
+| id | current compute node id
|
+| create_time | export time
|
+| storage_nodes | exported storage node JSON (or success message when `TO
FILE` is set) |
+
+### Supplement
+
+- When `databaseName` is not specified, storage nodes of all logical databases
are exported;
+- When `databaseName` is specified, only storage nodes of the specified
logical database are exported;
+- If the specified `databaseName` does not exist, export will fail;
+- When `filePath` is specified, the result is written to file and existing
file content will be overwritten;
+- Exported JSON contains connection information such as `username` and
`password`; protect the output properly.
+
+### Example
+
+```sql
+EXPORT STORAGE NODES;
+```
+
+```sql
+EXPORT STORAGE NODES FROM sharding_db TO FILE '/tmp/storage-nodes.json';
+```
+
+### Reserved word
+
+`EXPORT`, `STORAGE`, `NODES`, `FROM`, `TO`, `FILE`
+
+### Related links
+
+- [Reserved
word](/en/user-manual/shardingsphere-proxy/distsql/syntax/reserved-word/)
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/import-metadata.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/import-metadata.cn.md
new file mode 100644
index 00000000000..1b085e94a99
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/import-metadata.cn.md
@@ -0,0 +1,53 @@
++++
+title = "IMPORT METADATA"
+weight = 19
++++
+
+### 描述
+
+`IMPORT METADATA` 语法用于从文件或内联值导入集群元数据。
+
+### 语法
+
+{{< tabs >}}
+{{% tab name="语法" %}}
+```sql
+ImportMetaData ::=
+ 'IMPORT' 'METADATA' (metaDataValue | 'FROM' 'FILE' filePath)
+
+metaDataValue ::=
+ string
+
+filePath ::=
+ string
+```
+{{% /tab %}}
+{{% tab name="铁路图" %}}
+<iframe frameborder="0" name="diagram" id="diagram" width="100%"
height="100%"></iframe>
+{{% /tab %}}
+{{< /tabs >}}
+
+### 补充说明
+
+- `metaDataValue` 需要是通过 `EXPORT METADATA` 导出的 Base64 字符串；
+- `FROM FILE` 需要指向通过 `EXPORT METADATA TO FILE` 导出的 JSON 文件；
+- 如果导入元数据中包含已存在的逻辑库，导入会失败；
+- 如果文件不存在或内容格式不正确，导入会失败。
+
+### 示例
+
+```sql
+IMPORT METADATA FROM FILE '/tmp/metadata.json';
+```
+
+```sql
+IMPORT METADATA 'eyJtZXRhX2RhdGEiOns...';
+```
+
+### 保留字
+
+`IMPORT`、`METADATA`、`FROM`、`FILE`
+
+### 相关链接
+
+- [保留字](/cn/user-manual/shardingsphere-proxy/distsql/syntax/reserved-word/)
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/import-metadata.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/import-metadata.en.md
new file mode 100644
index 00000000000..07c5f295dcd
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-proxy/distsql/syntax/ral/import-metadata.en.md
@@ -0,0 +1,53 @@
++++
+title = "IMPORT METADATA"
+weight = 19
++++
+
+### Description
+
+The `IMPORT METADATA` syntax is used to import cluster metadata from file or
inline value.
+
+### Syntax
+
+{{< tabs >}}
+{{% tab name="Grammar" %}}
+```sql
+ImportMetaData ::=
+ 'IMPORT' 'METADATA' (metaDataValue | 'FROM' 'FILE' filePath)
+
+metaDataValue ::=
+ string
+
+filePath ::=
+ string
+```
+{{% /tab %}}
+{{% tab name="Railroad diagram" %}}
+<iframe frameborder="0" name="diagram" id="diagram" width="100%"
height="100%"></iframe>
+{{% /tab %}}
+{{< /tabs >}}
+
+### Supplement
+
+- `metaDataValue` should be a Base64 string exported by `EXPORT METADATA`;
+- `FROM FILE` should point to a JSON file exported by `EXPORT METADATA TO
FILE`;
+- If the imported metadata contains an existing logical database, import will
fail;
+- If the metadata file does not exist or content format is invalid, import
will fail.
+
+### Example
+
+```sql
+IMPORT METADATA FROM FILE '/tmp/metadata.json';
+```
+
+```sql
+IMPORT METADATA 'eyJtZXRhX2RhdGEiOns...';
+```
+
+### Reserved word
+
+`IMPORT`, `METADATA`, `FROM`, `FILE`
+
+### Related links
+
+- [Reserved
word](/en/user-manual/shardingsphere-proxy/distsql/syntax/reserved-word/)
