You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by du...@apache.org on 2022/07/13 08:51:15 UTC
[shardingsphere] branch master updated: refactor readwrite and parser doc (#19097)
This is an automated email from the ASF dual-hosted git repository.
duanzhengqiang 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 a6b616d9be3 refactor readwrite and parser doc (#19097)
a6b616d9be3 is described below
commit a6b616d9be30453db67e3db50b25152f9abd8016
Author: Chuxin Chen <ch...@qq.com>
AuthorDate: Wed Jul 13 16:51:10 2022 +0800
refactor readwrite and parser doc (#19097)
* refactor parser doc
* refactor readwrite-splitting yaml
* refactor parser yaml
* refactor read-write splitting springboot
* refactor parser springboot
* refactor readwrite-splitting spring name space
* refactor parser spring name space
---
.../java-api/rules/sql-parser.cn.md | 29 ++++++++++++++++-
.../java-api/rules/sql-parser.en.md | 29 ++++++++++++++++-
.../rules/readwrite-splitting.cn.md | 25 +++++++++++++--
.../rules/readwrite-splitting.en.md | 24 ++++++++++++++-
.../spring-boot-starter/rules/sql-parser.cn.md | 25 ++++++++++++++-
.../spring-boot-starter/rules/sql-parser.en.md | 24 ++++++++++++++-
.../rules/readwrite-splitting.cn.md | 29 ++++++++++++++++-
.../rules/readwrite-splitting.en.md | 28 ++++++++++++++++-
.../spring-namespace/rules/sql-parser.cn.md | 22 ++++++++++++-
.../spring-namespace/rules/sql-parser.en.md | 22 ++++++++++++-
.../yaml-config/rules/readwrite-splitting.cn.md | 36 ++++++++++++++++++++--
.../yaml-config/rules/readwrite-splitting.en.md | 34 +++++++++++++++++++-
.../yaml-config/rules/sql-parser.cn.md | 29 ++++++++++++++++-
.../yaml-config/rules/sql-parser.en.md | 29 ++++++++++++++++-
14 files changed, 369 insertions(+), 16 deletions(-)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser.cn.md
index 86eb04eda7e..05335bffe6d 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser.cn.md
@@ -3,7 +3,12 @@ title = "SQL 解析"
weight = 7
+++
-## 配置入口
+## 背景信息
+SQL 是使用者与数据库交流的标准语言。 SQL 解析引擎负责将 SQL 字符串解析为抽象语法树，供 Apache ShardingSphere 理解并实现其增量功能。
+目前支持 MySQL, PostgreSQL, SQLServer, Oracle, openGauss 以及符合 SQL92 规范的 SQL 方言。 由于 SQL 语法的复杂性，目前仍然存在少量不支持的 SQL。
+通过 Java API 形式使用 SQL 解析，可以方便得集成进入各种系统，灵活定制用户需求。
+
+## 参数解释
类名称：org.apache.shardingsphere.parser.config.SQLParserRuleConfiguration
@@ -25,3 +30,25 @@ weight = 7
|-------------------------|-------------|---------------------------------------------|--------------------------------------------|
| initialCapacity | int | 本地缓存初始容量 | 语法树本地缓存默认值 128，SQL 语句缓存默认值 2000 |
| maximumSize | long | 本地缓存最大容量 | 语法树本地缓存默认值 1024，SQL 语句缓存默认值 65535 |
+
+## 操作步骤
+
+1. 设置本地缓存配置
+2. 设置解析配置
+3. 使用解析引擎解析 SQL
+
+## 配置示例
+
+```java
+CacheOption cacheOption = new CacheOption(128, 1024L);
+SQLParserEngine parserEngine = new SQLParserEngine("MySQL", cacheOption);
+ParseASTNode parseASTNode = parserEngine.parse("SELECT t.id, t.name, t.age FROM table1 AS t ORDER BY t.id DESC;", false);
+SQLVisitorEngine visitorEngine = new SQLVisitorEngine("MySQL", "STATEMENT", false, new Properties());
+MySQLStatement sqlStatement = visitorEngine.visit(parseASTNode);
+System.out.println(sqlStatement.toString());
+```
+
+## 相关参考
+- [YAML 配置：SQL 解析](/cn/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser/)
+- [Spring Boot Starter：SQL 解析](/cn/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser/)
+- [Spring 命名空间：SQl解析](/cn/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser.en.md
index 65f6bc2c970..5d0c1c5dfd3 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser.en.md
@@ -3,7 +3,13 @@ title = "SQL Parser"
weight = 7
+++
-## Root Configuration
+## Background
+
+SQL is the standard language for users to communicate with databases. The SQL parsing engine is responsible for parsing the SQL string into an abstract syntax tree for Apache ShardingSphere to understand and implement its incremental function.
+Currently, MySQL, PostgreSQL, SQLServer, Oracle, openGauss and SQL dialects conforming to SQL92 specifications are supported. Due to the complexity of SQL syntax, there are still a few unsupported SQLs.
+By using SQL parsing in the form of Java API, you can easily integrate into various systems and flexibly customize user requirements.
+
+## Parameters
Class: org.apache.shardingsphere.parser.config.SQLParserRuleConfiguration
@@ -26,3 +32,24 @@ Attributes:
| initialCapacity | int | Initial capacity of local cache | parser syntax tree local cache default value 128, SQL statement cache default value 2000 |
| maximumSize(?) | long | Maximum capacity of local cache | The default value of local cache for parsing syntax tree is 1024, and the default value of sql statement cache is 65535 |
+## Procedure
+
+1. Set local cache configuration.
+2. Set resolution configuration.
+3. Use the parsing engine to parse SQL.
+
+## Sample
+
+```java
+CacheOption cacheOption = new CacheOption(128, 1024L);
+SQLParserEngine parserEngine = new SQLParserEngine("MySQL", cacheOption);
+ParseASTNode parseASTNode = parserEngine.parse("SELECT t.id, t.name, t.age FROM table1 AS t ORDER BY t.id DESC;", false);
+SQLVisitorEngine visitorEngine = new SQLVisitorEngine("MySQL", "STATEMENT", false, new Properties());
+MySQLStatement sqlStatement = visitorEngine.visit(parseASTNode);
+System.out.println(sqlStatement.toString());
+```
+
+## Related References
+- [YAML Configuration: SQL Parser](/en/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser/)
+- [Spring Boot Starter: SQL Parser](/en/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser/)
+- [Spring Namespace: SQL Parser](/en/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting.cn.md
index 8d14ed3bce9..ca82af7bbb7 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting.cn.md
@@ -3,7 +3,10 @@ title = "读写分离"
weight = 2
+++
-## 配置项说明
+## 背景信息
+读写分离 Spring Boot Starter 配置方式适用于使用 SpringBoot 的业务场景，能够最大程度地利用 SringBoot 配置初始化及 Bean 管理的能力，完成 ShardingSphereDataSource 对象的创建，减少不必要的编码工作。
+
+## 参数解释
### 静态读写分离
@@ -33,6 +36,24 @@ spring.shardingsphere.rules.readwrite-splitting.load-balancers.<load-balance-alg
spring.shardingsphere.rules.readwrite-splitting.load-balancers.<load-balance-algorithm-name>.props.xxx= # 负载均衡算法属性配置
```
-
算法类型的详情，请参见[内置负载均衡算法列表](/cn/user-manual/shardingsphere-jdbc/builtin-algorithm/load-balance)。
查询一致性路由的详情，请参见[使用规范](/cn/features/readwrite-splitting/use-norms)。
+
+## 操作步骤
+1. 添加读写分离数据源
+2. 设置负载均衡算法
+3. 使用读写分离数据源
+
+## 配置示例
+```properties
+spring.shardingsphere.rules.readwrite-splitting.data-sources.readwrite_ds.static-strategy.write-data-source-name=write-ds
+spring.shardingsphere.rules.readwrite-splitting.data-sources.readwrite_ds.static-strategy.read-data-source-names=read-ds-0,read-ds-1
+spring.shardingsphere.rules.readwrite-splitting.data-sources.readwrite_ds.load-balancer-name=round_robin
+spring.shardingsphere.rules.readwrite-splitting.load-balancers.round_robin.type=ROUND_ROBIN
+```
+
+## 相关参考
+- [核心特性：读写分离](/cn/features/readwrite-splitting/)
+- [Java API：读写分离](/cn/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting/)
+- [YAML配置：读写分离](/cn/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting/)
+- [Spring 命名空间：读写分离](/cn/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting.en.md
index 8ea107be5fc..16b1a4f95a9 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting.en.md
@@ -3,7 +3,10 @@ title = "Readwrite splitting"
weight = 2
+++
-## Configuration Item Explanation
+## Background
+The read-write splitting configuration method of Spring Boot Starter is suitable for business scenarios using SpringBoot and can maximize the capabilities of initializing SringBoot configuration process and bean management to complete the creation of ShardingSphereDataSource object, reducing unnecessary coding work.
+
+## Parameters Explained
### Static Readwrite-splitting
@@ -35,3 +38,22 @@ spring.shardingsphere.rules.readwrite-splitting.load-balancers.<load-balance-alg
Please refer to [Built-in Load Balance Algorithm List](/en/user-manual/shardingsphere-jdbc/builtin-algorithm/load-balance) for more details about type of algorithm.
Please refer to [Use Norms](/en/features/readwrite-splitting/use-norms) for more details about query consistent routing.
+
+## Operating Procedure
+1. Add read/write splitting data source.
+2. Set load-balancing algorithm.
+3. Use read/write splitting data source.
+
+## Configuration Examples
+```properties
+spring.shardingsphere.rules.readwrite-splitting.data-sources.readwrite_ds.static-strategy.write-data-source-name=write-ds
+spring.shardingsphere.rules.readwrite-splitting.data-sources.readwrite_ds.static-strategy.read-data-source-names=read-ds-0,read-ds-1
+spring.shardingsphere.rules.readwrite-splitting.data-sources.readwrite_ds.load-balancer-name=round_robin
+spring.shardingsphere.rules.readwrite-splitting.load-balancers.round_robin.type=ROUND_ROBIN
+```
+
+## References
+- [Read-write splitting-Core features](/en/features/readwrite-splitting/)
+- [Java API: read-write splitting](/en/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting/)
+- [YAML Configuration: read-write splitting](/en/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting/)
+- [Spring namespace: read-write splitting](/en/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser.cn.md
index 67781d3b987..5dd8ed9acc5 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser.cn.md
@@ -3,8 +3,10 @@ title = "SQL 解析"
weight = 6
+++
-## 配置项说明
+## 背景信息
+Spring Boot Starter 的配置方式适用于使用 SpringBoot 的业务场景。使用这种方式，能够最大程度地利用 SpringBoot 配置初始化以及 Bean 管理的能力，从而达到简化代码开发的目的。
+## 参数解释
```properties
spring.shardingsphere.rules.sql-parser.sql-comment-parse-enabled= # 是否解析 SQL 注释
@@ -14,3 +16,24 @@ spring.shardingsphere.rules.sql-parser.sql-statement-cache.maximum-size= # SQL
spring.shardingsphere.rules.sql-parser.parse-tree-cache.initial-capacity= # 解析树本地缓存初始容量
spring.shardingsphere.rules.sql-parser.parse-tree-cache.maximum-size= # 解析树本地缓存最大容量
```
+
+## 操作步骤
+1. 设置本地缓存配置
+2. 设置解析配置
+3. 使用解析引擎解析 SQL
+
+## 配置示例
+```properties
+spring.shardingsphere.rules.sql-parser.sql-comment-parse-enabled=true
+
+spring.shardingsphere.rules.sql-parser.sql-statement-cache.initial-capacity=2000
+spring.shardingsphere.rules.sql-parser.sql-statement-cache.maximum-size=65535
+
+spring.shardingsphere.rules.sql-parser.parse-tree-cache.initial-capacity=128
+spring.shardingsphere.rules.sql-parser.parse-tree-cache.maximum-size=1024
+```
+
+## 相关参考
+- [JAVA API：SQL 解析](/cn/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser/)
+- [YAML 配置：SQL 解析](/cn/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser/)
+- [Spring 命名空间：SQl解析](/cn/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser.en.md
index ac442056a59..4c0701b4aa7 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser.en.md
@@ -3,8 +3,10 @@ title = "SQL Parser"
weight = 6
+++
-## Configuration Item Explanation
+## Background
+The configuration method of Spring Boot Starter is applicable to business scenarios using SpringBoot. In this way, the SpringBoot configuration initialization and bean management capabilities can be used to the greatest extent, so as to simplify code development.
+## Parameters
```properties
spring.shardingsphere.rules.sql-parser.sql-comment-parse-enabled= # Whether to parse SQL comments
@@ -15,3 +17,23 @@ spring.shardingsphere.rules.sql-parser.parse-tree-cache.initial-capacity= # Init
spring.shardingsphere.rules.sql-parser.parse-tree-cache.maximum-size= # Maximum local cache capacity of parse tree
```
+## Procedure
+1. Set local cache configuration
+2. Set parser configuration
+3. use the parser engine to parse SQL
+
+## Sample
+```properties
+spring.shardingsphere.rules.sql-parser.sql-comment-parse-enabled=true
+
+spring.shardingsphere.rules.sql-parser.sql-statement-cache.initial-capacity=2000
+spring.shardingsphere.rules.sql-parser.sql-statement-cache.maximum-size=65535
+
+spring.shardingsphere.rules.sql-parser.parse-tree-cache.initial-capacity=128
+spring.shardingsphere.rules.sql-parser.parse-tree-cache.maximum-size=1024
+```
+
+## Related References
+- [JAVA API: SQL Parser](/en/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser/)
+- [YAML Configuration: SQL Parser](/en/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser/)
+- [Spring Namespace: SQL Parser](/en/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting.cn.md
index b9d17eb702c..859f4599400 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting.cn.md
@@ -3,7 +3,10 @@ title = "读写分离"
weight = 2
+++
-## 配置项说明
+## 背景信息
+读写分离 Spring 命名空间的配置方式，适用于传统的 Spring 项目，通过命名空间 xml 配置文件的方式配置分片规则和属性，由 Spring 完成 ShardingSphereDataSource 对象的创建和管理，避免额外的编码工作。
+
+## 参数解释
命名空间：[http://shardingsphere.apache.org/schema/shardingsphere/readwrite-splitting/readwrite-splitting-5.1.2.xsd](http://shardingsphere.apache.org/schema/shardingsphere/readwrite-splitting/readwrite-splitting-5.1.2.xsd)
@@ -52,3 +55,27 @@ weight = 2
算法类型的详情，请参见[内置负载均衡算法列表](/cn/user-manual/shardingsphere-jdbc/builtin-algorithm/load-balance)。
查询一致性路由的详情，请参见[使用规范](/cn/features/readwrite-splitting/use-norms)。
+
+## 操作步骤
+1. 添加读写分离数据源
+2. 设置负载均衡算法
+3. 使用读写分离数据源
+
+## 配置示例
+```xml
+<readwrite-splitting:load-balance-algorithm id="randomStrategy" type="RANDOM" />
+
+<readwrite-splitting:rule id="readWriteSplittingRule">
+ <readwrite-splitting:data-source-rule id="demo_ds" load-balance-algorithm-ref="randomStrategy">
+ <readwrite-splitting:static-strategy id="staticStrategy" write-data-source-name="demo_write_ds" read-data-source-names="demo_read_ds_0, demo_read_ds_1"/>
+ </readwrite-splitting:data-source-rule>
+</readwrite-splitting:rule>
+
+<shardingsphere:data-source id="readWriteSplittingDataSource" data-source-names="demo_write_ds, demo_read_ds_0, demo_read_ds_1" rule-refs="readWriteSplittingRule" />
+```
+
+## 相关参考
+- [核心特性：读写分离](/cn/features/readwrite-splitting/)
+- [Java API：读写分离](/cn/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting/)
+- [YAML配置：读写分离](/cn/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting/)
+- [Spring Boot Starter：读写分离](/cn/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting.en.md
index 38d63c28931..a40f9bb6fa7 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting.en.md
@@ -3,8 +3,10 @@ title = "Readwrite-splitting"
weight = 2
+++
-## Configuration Item Explanation
+## Background
+Spring namespace read/write splitting configuration method is suitable for conventional Spring projects, determine sharding rules and properties through namespace XML configuration files, and let Spring do the creation and management of ShardingSphereDataSource objects, avoiding additional coding work.
+## Parameters Explained
Namespace: [http://shardingsphere.apache.org/schema/shardingsphere/readwrite-splitting/readwrite-splitting-5.1.2.xsd](http://shardingsphere.apache.org/schema/shardingsphere/readwrite-splitting/readwrite-splitting-5.1.2.xsd)
\<readwrite-splitting:rule />
@@ -52,3 +54,27 @@ Namespace: [http://shardingsphere.apache.org/schema/shardingsphere/readwrite-spl
Please refer to [Built-in Load Balance Algorithm List](/en/user-manual/shardingsphere-jdbc/builtin-algorithm/load-balance) for more details about type of algorithm.
Please refer to [Use Norms](/en/features/readwrite-splitting/use-norms) for more details about query consistent routing.
+
+## Operating Procedures
+1. Add read/write splitting data source.
+2. Set the load balancing algorithm.
+3. Using read/write splitting data sources.
+
+## Configuration Example
+```xml
+<readwrite-splitting:load-balance-algorithm id="randomStrategy" type="RANDOM" />
+
+<readwrite-splitting:rule id="readWriteSplittingRule">
+ <readwrite-splitting:data-source-rule id="demo_ds" load-balance-algorithm-ref="randomStrategy">
+ <readwrite-splitting:static-strategy id="staticStrategy" write-data-source-name="demo_write_ds" read-data-source-names="demo_read_ds_0, demo_read_ds_1"/>
+ </readwrite-splitting:data-source-rule>
+</readwrite-splitting:rule>
+
+<shardingsphere:data-source id="readWriteSplittingDataSource" data-source-names="demo_write_ds, demo_read_ds_0, demo_read_ds_1" rule-refs="readWriteSplittingRule" />
+```
+
+## Related References
+- [Read-write splitting-Core features](/en/features/readwrite-splitting/)
+- [Java API: read-write splitting](/en/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting/)
+- [YAML Configuration: read-write splitting](/en/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting/)
+- [Spring Boot Starter: read-write splitting](/en/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser.cn.md
index 54e5ddacc8d..b5d5a4e8c03 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser.cn.md
@@ -3,7 +3,10 @@ title = "SQL解析"
weight = 6
+++
-## 配置项说明
+## 背景信息
+Spring 命名空间的配置方式，适用于传统的 Spring 项目，它通过命名空间 xml 配置文件的方式配置SQL 解析规则和属性。
+
+## 参数解释
命名空间：[http://shardingsphere.apache.org/schema/shardingsphere/sql-parser/sql-parser-5.1.2.xsd](http://shardingsphere.apache.org/schema/shardingsphere/sql-parser/sql-parser-5.1.2.xsd)
@@ -23,3 +26,20 @@ weight = 6
| id | 属性 | 本地缓存配置项名称 |
| initial-capacity | 属性 | 本地缓存初始容量 |
| maximum-size | 属性 | 本地缓存最大容量 |
+
+## 操作步骤
+1. 设置本地缓存配置
+2. 设置解析配置
+3. 使用解析引擎解析 SQL
+
+## 配置示例
+```xml
+<sql-parser:rule id="sqlParseRule" sql-comment-parse-enable="true" parse-tree-cache-ref="parseTreeCache" sql-statement-cache-ref="sqlStatementCache" />
+<sql-parser:cache-option id="sqlStatementCache" initial-capacity="1024" maximum-size="1024"/>
+<sql-parser:cache-option id="parseTreeCache" initial-capacity="1024" maximum-size="1024"/>
+```
+
+## 相关参考
+- [JAVA API：SQL 解析](/cn/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser/)
+- [YAML 配置：SQL 解析](/cn/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser/)
+- [Spring Boot Starter：SQL 解析](/cn/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser.en.md
index adde25f6fbe..931cba70202 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser.en.md
@@ -3,7 +3,10 @@ title = "SQL Parser"
weight = 6
+++
-## Configuration Item Explanation
+## Background
+Spring namespace's SQL parser configuration applies to traditional Spring projects. SQL parsing rules and attributes can be configured through the XML configuration files of the namespace.
+
+## Parameters
Namespace：[http://shardingsphere.apache.org/schema/shardingsphere/sql-parser/sql-parser-5.1.2.xsd](http://shardingsphere.apache.org/schema/shardingsphere/sql-parser/sql-parser-5.1.2.xsd)
@@ -23,3 +26,20 @@ Namespace：[http://shardingsphere.apache.org/schema/shardingsphere/sql-parser/s
| id | Attribute | Local cache configuration item name |
| initial-capacity | Attribute | Initial capacity of local cache |
| maximum-size | Attribute | Maximum capacity of local cache |
+
+## Procedure
+1. Set local cache configuration.
+2. Set parser configuration.
+3. Parse SQL with a parsing engine.
+
+## Sample
+```xml
+<sql-parser:rule id="sqlParseRule" sql-comment-parse-enable="true" parse-tree-cache-ref="parseTreeCache" sql-statement-cache-ref="sqlStatementCache" />
+<sql-parser:cache-option id="sqlStatementCache" initial-capacity="1024" maximum-size="1024"/>
+<sql-parser:cache-option id="parseTreeCache" initial-capacity="1024" maximum-size="1024"/>
+```
+
+## Related References
+- [JAVA API: SQL Parser](/en/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser/)
+- [YAML Configuration: SQL Parser](/en/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser/)
+- [Spring Boot Starter: SQL Parser](/en/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting.cn.md
index 2391e5f955c..023d6bc564c 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting.cn.md
@@ -3,7 +3,11 @@ title = "读写分离"
weight = 2
+++
-## 配置项说明
+## 背景信息
+
+读写分离 YAML 配置方式可读性高，通过 YAML 格式，能够快速地理解读写分片规则之间的依赖关系，ShardingSphere 会根据 YAML 配置，自动完成 ShardingSphereDataSource 对象的创建，减少用户不必要的编码工作。
+
+## 参数解释
### 静态读写分离
@@ -44,6 +48,34 @@ rules:
props: # 负载均衡算法属性配置
# ...
```
-
算法类型的详情，请参见[内置负载均衡算法列表](/cn/user-manual/shardingsphere-jdbc/builtin-algorithm/load-balance)。
查询一致性路由的详情，请参见[使用规范](/cn/features/readwrite-splitting/use-norms)。
+
+## 操作步骤
+1. 添加读写分离数据源
+2. 设置负载均衡算法
+3. 使用读写分离数据源
+
+## 配置示例
+```yaml
+rules:
+- !READWRITE_SPLITTING
+ dataSources:
+ readwrite_ds:
+ staticStrategy:
+ writeDataSourceName: write_ds
+ readDataSourceNames:
+ - read_ds_0
+ - read_ds_1
+ loadBalancerName: random
+ loadBalancers:
+ random:
+ type: RANDOM
+```
+
+## 相关参考
+
+- [核心特性：读写分离](/cn/features/readwrite-splitting/)
+- [Java API：读写分离](/cn/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting/)
+- [Spring Boot Starter：读写分离](/cn/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting/)
+- [Spring 命名空间：读写分离](/cn/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting.en.md
index 6639e6a4c46..8a629ae8017 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/readwrite-splitting.en.md
@@ -3,7 +3,10 @@ title = "Readwrite-splitting"
weight = 2
+++
-## Configuration Item Explanation
+## Background
+Read/write splitting YAML configuration is highly readable. The YAML format enables you to quickly understand the dependencies between read/write sharding rules. ShardingSphere automatically creates the ShardingSphereDataSource object according to the YAML configuration, which reduces unnecessary coding for users.
+
+## Parameters
### Static Readwrite-splitting
@@ -47,3 +50,32 @@ rules:
Please refer to [Built-in Load Balance Algorithm List](/en/user-manual/shardingsphere-jdbc/builtin-algorithm/load-balance) for more details about type of algorithm.
Please refer to [Use Norms](/en/features/readwrite-splitting/use-norms) for more details about query consistent routing.
+
+## Procedure
+1. Add read/write splitting data source.
+2. Set the load balancer algorithm.
+3. Use read/write data source.
+
+## Sample
+```yaml
+rules:
+- !READWRITE_SPLITTING
+ dataSources:
+ readwrite_ds:
+ staticStrategy:
+ writeDataSourceName: write_ds
+ readDataSourceNames:
+ - read_ds_0
+ - read_ds_1
+ loadBalancerName: random
+ loadBalancers:
+ random:
+ type: RANDOM
+```
+
+## Related References
+
+- [Read-write splitting-Core features](/en/features/readwrite-splitting/)
+- [Java API: read-write splitting](/en/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting/)
+- [Spring Boot Starter: read-write splitting](/en/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/readwrite-splitting/)
+- [Spring namespace: read-write splitting](/en/user-manual/shardingsphere-jdbc/spring-namespace/rules/readwrite-splitting/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser.cn.md
index 19571526050..7241127d886 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser.cn.md
@@ -3,7 +3,10 @@ title = "SQL 解析"
weight = 7
+++
-## 配置项说明
+## 背景信息
+SQL 解析 YAML 配置方式具有可读性高，使用简单的特点。通过 YAML 文件的方式，用户可以将代码与配置分离，并且根据需要方便地修改配置文件。
+
+## 参数解释
```yaml
rules:
@@ -16,3 +19,27 @@ rules:
initialCapacity: # 本地缓存初始容量
maximumSize: # 本地缓存最大容量
```
+
+## 操作步骤
+
+1. 设置本地缓存配置
+2. 设置解析配置
+3. 使用解析引擎解析 SQL
+
+## 配置示例
+```yaml
+rules:
+ - !SQL_PARSER
+ sqlCommentParseEnabled: true
+ sqlStatementCache:
+ initialCapacity: 2000
+ maximumSize: 65535
+ parseTreeCache:
+ initialCapacity: 128
+ maximumSize: 1024
+```
+
+## 相关参考
+- [JAVA API：SQL 解析](/cn/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser/)
+- [Spring Boot Starter：SQL 解析](/cn/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser/)
+- [Spring 命名空间：SQl解析](/cn/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser/)
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser.en.md
index 3388d8f1d60..5cdb88146ed 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-parser.en.md
@@ -3,7 +3,11 @@ title = "SQL-parser"
weight = 7
+++
-## Configuration Item Explanation
+## Background
+
+The SQL parser YAML configuration is readable and easy to use. The YAML files allow you to separate the code from the configuration, and easily modify the configuration file as needed.
+
+## Parameters
```yaml
rules:
@@ -16,3 +20,26 @@ rules:
initialCapacity: # Initial capacity of local cache
maximumSize: # Maximum capacity of local cache
```
+
+## Procedure
+1. Set local cache configuration.
+2. Set parser configuration.
+3. Use a parsing engine to parse SQL.
+
+## Sample
+```yaml
+rules:
+ - !SQL_PARSER
+ sqlCommentParseEnabled: true
+ sqlStatementCache:
+ initialCapacity: 2000
+ maximumSize: 65535
+ parseTreeCache:
+ initialCapacity: 128
+ maximumSize: 1024
+```
+
+## Related References
+- [JAVA API: SQL Parsing](/en/user-manual/shardingsphere-jdbc/java-api/rules/sql-parser/)
+- [Spring Boot Starter: SQL Parsing](/en/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/sql-parser/)
+- [Spring namespace: SQL Parsing](/en/user-manual/shardingsphere-jdbc/spring-namespace/rules/sql-parser/)