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 d7a249fd8ac Add broadcast, sharding-cache and single java api doc
(#29684)
d7a249fd8ac is described below
commit d7a249fd8acf8bee64a070993fb22fb194429bd8
Author: Zhengqiang Duan <[email protected]>
AuthorDate: Tue Jan 9 16:25:25 2024 +0800
Add broadcast, sharding-cache and single java api doc (#29684)
* Add broadcast, sharding-cache and single java api doc
* fix typo
* fix typo
---
.../java-api/rules/broadcast.cn.md | 45 +++++++++++
.../java-api/rules/broadcast.en.md | 46 ++++++++++++
.../java-api/rules/encrypt.cn.md | 2 +-
.../java-api/rules/encrypt.en.md | 2 +-
.../shardingsphere-jdbc/java-api/rules/mask.cn.md | 2 +-
.../shardingsphere-jdbc/java-api/rules/mask.en.md | 2 +-
.../shardingsphere-jdbc/java-api/rules/mix.cn.md | 2 +-
.../shardingsphere-jdbc/java-api/rules/mix.en.md | 2 +-
.../java-api/rules/readwrite-splitting.cn.md | 2 +-
.../java-api/rules/readwrite-splitting.en.md | 2 +-
.../java-api/rules/shadow.cn.md | 2 +-
.../java-api/rules/shadow.en.md | 2 +-
.../java-api/rules/sharding-cache.cn.md | 87 ++++++++++++++++++++++
.../java-api/rules/sharding-cache.en.md | 87 ++++++++++++++++++++++
.../java-api/rules/single.cn.md | 35 +++++++++
.../java-api/rules/single.en.md | 35 +++++++++
.../java-api/rules/sql-parser.cn.md | 2 +-
.../java-api/rules/sql-parser.en.md | 2 +-
.../java-api/rules/sql-translator.cn.md | 23 +++++-
.../java-api/rules/sql-translator.en.md | 23 +++++-
.../java-api/rules/transaction.cn.md | 2 +-
.../java-api/rules/transaction.en.md | 2 +-
.../yaml-config/rules/sql-translator.cn.md | 22 +++++-
.../yaml-config/rules/sql-translator.en.md | 21 +++++-
24 files changed, 432 insertions(+), 20 deletions(-)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/broadcast.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/broadcast.cn.md
new file mode 100644
index 00000000000..5ca515b8685
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/broadcast.cn.md
@@ -0,0 +1,45 @@
++++
+title = "广播表"
+weight = 2
++++
+
+广播表 Java API 规则配置允许用户直接通过编写 Java 代码的方式，完成 ShardingSphereDataSource 对象的创建，Java
API 的配置方式非常灵活，不需要依赖额外的 jar 包就能够集成各种类型的业务系统。
+
+## 参数解释
+
+类名称：org.apache.shardingsphere.broadcast.api.config.BroadcastRuleConfiguration
+
+可配置属性：
+
+| *名称* | *数据类型* |
*说明* | *默认值* |
+|---------------------------|---------------------------------------------|------------|-------|
+| tables (+) | Collection\<String\> | 广播表规则配置 | |
+
+## 配置示例
+
+广播表 Java API 配置示例如下：
+
+```java
+public final class ShardingDatabasesAndTablesConfigurationPrecise {
+
+ @Override
+ public DataSource getDataSource() throws SQLException {
+ return
ShardingSphereDataSourceFactory.createDataSource(createDataSourceMap(),
Arrays.asList(createBroadcastRuleConfiguration()), new Properties());
+ }
+
+ private Map<String, DataSource> createDataSourceMap() {
+ Map<String, DataSource> result = new HashMap<>();
+ result.put("demo_ds_0", DataSourceUtil.createDataSource("demo_ds_0"));
+ result.put("demo_ds_1", DataSourceUtil.createDataSource("demo_ds_1"));
+ return result;
+ }
+
+ private BroadcastRuleConfiguration createBroadcastRuleConfiguration() {
+ return new
BroadcastRuleConfiguration(Collections.singletonList("t_address"));
+ }
+}
+```
+
+## 相关参考
+
+- [YAML
配置：广播表](/cn/user-manual/shardingsphere-jdbc/yaml-config/rules/broadcast/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/broadcast.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/broadcast.en.md
new file mode 100644
index 00000000000..7aed84d3796
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/broadcast.en.md
@@ -0,0 +1,46 @@
++++
+title = "Broadcast Table"
+weight = 2
++++
+
+## Background
+
+The Java API rule configuration for broadcast, which allows users to create
ShardingSphereDataSource objects directly by writing Java code, is flexible
enough to integrate various types of business systems without relying on
additional jar packages.
+
+## Parameters
+
+Class：org.apache.shardingsphere.broadcast.api.config.BroadcastRuleConfiguration
+
+Attributes：
+
+| *name* | *DataType* | *Description*
| *Default Value* |
+|---------------------------|---------------------------------------------|------------|-------|
+| tables (+) | Collection\<String\> | Broadcast table rules
| |
+
+## Sample
+
+The following is an example of the broadcast table Java API configuration:
+
+```java
+public final class ShardingDatabasesAndTablesConfigurationPrecise {
+
+ @Override
+ public DataSource getDataSource() throws SQLException {
+ return
ShardingSphereDataSourceFactory.createDataSource(createDataSourceMap(),
Arrays.asList(createBroadcastRuleConfiguration()), new Properties());
+ }
+
+ private Map<String, DataSource> createDataSourceMap() {
+ Map<String, DataSource> result = new HashMap<>();
+ result.put("demo_ds_0", DataSourceUtil.createDataSource("demo_ds_0"));
+ result.put("demo_ds_1", DataSourceUtil.createDataSource("demo_ds_1"));
+ return result;
+ }
+
+ private BroadcastRuleConfiguration createBroadcastRuleConfiguration() {
+ return new
BroadcastRuleConfiguration(Collections.singletonList("t_address"));
+ }
+}
+```
+
+## Related References
+- [YAML Configuration:
Broadcast](/en/user-manual/shardingsphere-jdbc/yaml-config/rules/broadcast/)
\ No newline at end of file
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/encrypt.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/encrypt.cn.md
index 41e8ba484b8..9ecd5ea5acb 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/encrypt.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/encrypt.cn.md
@@ -1,6 +1,6 @@
+++
title = "数据加密"
-weight = 4
+weight = 5
+++
## 背景信息
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/encrypt.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/encrypt.en.md
index 3e4d321efb5..41196c5727b 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/encrypt.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/encrypt.en.md
@@ -1,6 +1,6 @@
+++
title = "Encryption"
-weight = 4
+weight = 5
+++
## Background
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mask.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mask.cn.md
index 333c41a5f5a..0b533f79274 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mask.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mask.cn.md
@@ -1,6 +1,6 @@
+++
title = "数据脱敏"
-weight = 5
+weight = 6
+++
## 背景信息
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mask.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mask.en.md
index 82193d435f9..5cefbe31797 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mask.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mask.en.md
@@ -1,6 +1,6 @@
+++
title = "Data Masking"
-weight = 5
+weight = 6
+++
## Background
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mix.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mix.cn.md
index 03c8b9d0d1a..7dda870ce5e 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mix.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mix.cn.md
@@ -1,6 +1,6 @@
+++
title = "混合规则"
-weight = 9
+weight = 10
+++
## 背景信息
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mix.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mix.en.md
index 70297088984..d5efc517b47 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mix.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/mix.en.md
@@ -1,6 +1,6 @@
+++
title = "Mixed Rules"
-weight = 9
+weight = 10
+++
## Background
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting.cn.md
index 1a52166f5d6..479ce677c31 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting.cn.md
@@ -1,6 +1,6 @@
+++
title = "读写分离"
-weight = 2
+weight = 3
+++
## 背景信息
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting.en.md
index 706f26f415d..2f655ef05f0 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/readwrite-splitting.en.md
@@ -1,6 +1,6 @@
+++
title = "Readwrite-splitting"
-weight = 2
+weight = 3
+++
## Background
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/shadow.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/shadow.cn.md
index 46a0b8b6303..1b75c8cb1b8 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/shadow.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/shadow.cn.md
@@ -1,6 +1,6 @@
+++
title = "影子库"
-weight = 6
+weight = 7
+++
## 背景信息
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/shadow.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/shadow.en.md
index c3c94636f22..4bcbe458e19 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/shadow.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/shadow.en.md
@@ -1,6 +1,6 @@
+++
title = "Shadow DB"
-weight = 6
+weight = 7
+++
## Background
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sharding-cache.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sharding-cache.cn.md
new file mode 100644
index 00000000000..c6a615c67bb
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sharding-cache.cn.md
@@ -0,0 +1,87 @@
++++
+title = "数据分片路由缓存"
+weight = 11
++++
+
+## 背景信息
+
+该项功能为**实验性功能**，需要与数据分片功能同时使用。
+数据分片路由缓存会将逻辑 SQL、分片键实际参数值、路由结果放入缓存中，以空间换时间，减少路由逻辑对 CPU 的使用。
+
+建议仅在满足以下条件的情况下启用：
+- 纯 OLTP 场景
+- ShardingSphere 进程所在机器 CPU 已达到瓶颈
+- CPU 开销主要在于 ShardingSphere 路由逻辑
+- 所有 SQL 已经最优且每次 SQL 执行都能命中单一分片
+
+在不满足以上条件的情况下使用，可能对 SQL 的执行延时不会有明显改善，同时会增加内存的压力。
+
+## 参数解释
+
+类名称：org.apache.shardingsphere.sharding.api.config.cache.ShardingCacheConfiguration
+
+可配置属性：
+
+| *名称* | *数据类型*
| *说明* | *默认值* |
+|-----------------------|------------------------------------------------------|----------------|-------|
+| allowedMaxSqlLength | int
| 允许缓存的 SQL 长度限制 | - |
+| routeCache |
org.apache.shardingsphere.sharding.api.config.cache.ShardingCacheOptionsConfiguration
| 路由缓存 | - |
+
+类名称：org.apache.shardingsphere.sharding.api.config.cache.ShardingCacheOptionsConfiguration
+
+可配置属性：
+
+| *名称* | *数据类型*
| *说明* | *默认值* |
+|-----------------------|------------------------------------------------------|----------------|-------|
+| softValues | boolean
| 是否软引用缓存值 | - |
+| initialCapacity | int | 缓存初始容量 | - |
+| maximumSize | int | 缓存最大容量 | - |
+
+## 配置示例
+
+```java
+public final class ShardingDatabasesAndTablesConfigurationPrecise {
+
+ @Override
+ public DataSource getDataSource() throws SQLException {
+ return
ShardingSphereDataSourceFactory.createDataSource(createDataSourceMap(),
Arrays.asList(createShardingRuleConfiguration(),
createBroadcastRuleConfiguration())), new Properties());
+ }
+
+ private ShardingRuleConfiguration createShardingRuleConfiguration() {
+ ShardingRuleConfiguration result = new ShardingRuleConfiguration();
+ result.getTables().add(getOrderTableRuleConfiguration());
+ result.getTables().add(getOrderItemTableRuleConfiguration());
+ // ...
+ result.setShardingCache(new ShardingCacheConfiguration(512, new
ShardingCacheConfiguration.RouteCacheConfiguration(65536, 262144, true)));
+ return result;
+ }
+
+ private ShardingTableRuleConfiguration getOrderTableRuleConfiguration() {
+ ShardingTableRuleConfiguration result = new
ShardingTableRuleConfiguration("t_order", "demo_ds_${0..1}.t_order_${[0, 1]}");
+ result.setKeyGenerateStrategy(new
KeyGenerateStrategyConfiguration("order_id", "snowflake"));
+ result.setAuditStrategy(new
ShardingAuditStrategyConfiguration(Collections.singleton("sharding_key_required_auditor"),
true));
+ return result;
+ }
+
+ private ShardingTableRuleConfiguration
getOrderItemTableRuleConfiguration() {
+ ShardingTableRuleConfiguration result = new
ShardingTableRuleConfiguration("t_order_item",
"demo_ds_${0..1}.t_order_item_${[0, 1]}");
+ result.setKeyGenerateStrategy(new
KeyGenerateStrategyConfiguration("order_item_id", "snowflake"));
+ return result;
+ }
+
+ private Map<String, DataSource> createDataSourceMap() {
+ Map<String, DataSource> result = new HashMap<>();
+ result.put("demo_ds_0", DataSourceUtil.createDataSource("demo_ds_0"));
+ result.put("demo_ds_1", DataSourceUtil.createDataSource("demo_ds_1"));
+ return result;
+ }
+
+ private BroadcastRuleConfiguration createBroadcastRuleConfiguration() {
+ return new
BroadcastRuleConfiguration(Collections.singletonList("t_address"));
+ }
+}
+```
+
+## 相关参考
+
+- [核心特性：数据分片](/cn/features/sharding/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sharding-cache.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sharding-cache.en.md
new file mode 100644
index 00000000000..30e4a461616
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sharding-cache.en.md
@@ -0,0 +1,87 @@
++++
+title = "Cache for Sharding Route"
+weight = 11
++++
+
+## Background
+
+This feature is **experimental** and needs to be used with the data sharding
rule.
+The cache for sharding route will put the logical SQL, the parameter value of
the shard key, and the routing result into the cache, exchange space for time,
and reduce CPU usage of the routing logic.
+
+We recommend enabling it only if the following conditions are met:
+- Pure OLTP scenarios.
+- The CPU of the machine which deployed the ShardingSphere process has reached
the bottleneck.
+- Most of the CPUs are used by ShardingSphere routing logic.
+- All SQLs are optimized and each SQL execution could be routed to a single
data node.
+
+If the above conditions are not met, the execution delay of SQL may not be
significantly improved, and the memory pressure will be increased.
+
+## Parameters
+
+Class：org.apache.shardingsphere.sharding.api.config.cache.ShardingCacheConfiguration
+
+Attributes：
+
+| *name* | *DataType* | *Description*
| *Default Value* |
+|-----------------------|------------------------------------------------------|----------------|-------|
+| allowedMaxSqlLength | int
| 允许缓存的 SQL 长度限制 | - |
+| routeCache |
org.apache.shardingsphere.sharding.api.config.cache.ShardingCacheOptionsConfiguration
| 路由缓存 | - |
+
+Class：org.apache.shardingsphere.sharding.api.config.cache.ShardingCacheOptionsConfiguration
+
+Attributes：
+
+| *name* | *DataType* | *Description*
| *Default Value* |
+|-----------------------|------------------------------------------------------|----------------|-------|
+| softValues | boolean
| 是否软引用缓存值 | - |
+| initialCapacity | int | 缓存初始容量 | - |
+| maximumSize | int | 缓存最大容量 | - |
+
+## Sample
+
+```java
+public final class ShardingDatabasesAndTablesConfigurationPrecise {
+
+ @Override
+ public DataSource getDataSource() throws SQLException {
+ return
ShardingSphereDataSourceFactory.createDataSource(createDataSourceMap(),
Arrays.asList(createShardingRuleConfiguration(),
createBroadcastRuleConfiguration())), new Properties());
+ }
+
+ private ShardingRuleConfiguration createShardingRuleConfiguration() {
+ ShardingRuleConfiguration result = new ShardingRuleConfiguration();
+ result.getTables().add(getOrderTableRuleConfiguration());
+ result.getTables().add(getOrderItemTableRuleConfiguration());
+ // ...
+ result.setShardingCache(new ShardingCacheConfiguration(512, new
ShardingCacheConfiguration.RouteCacheConfiguration(65536, 262144, true)));
+ return result;
+ }
+
+ private ShardingTableRuleConfiguration getOrderTableRuleConfiguration() {
+ ShardingTableRuleConfiguration result = new
ShardingTableRuleConfiguration("t_order", "demo_ds_${0..1}.t_order_${[0, 1]}");
+ result.setKeyGenerateStrategy(new
KeyGenerateStrategyConfiguration("order_id", "snowflake"));
+ result.setAuditStrategy(new
ShardingAuditStrategyConfiguration(Collections.singleton("sharding_key_required_auditor"),
true));
+ return result;
+ }
+
+ private ShardingTableRuleConfiguration
getOrderItemTableRuleConfiguration() {
+ ShardingTableRuleConfiguration result = new
ShardingTableRuleConfiguration("t_order_item",
"demo_ds_${0..1}.t_order_item_${[0, 1]}");
+ result.setKeyGenerateStrategy(new
KeyGenerateStrategyConfiguration("order_item_id", "snowflake"));
+ return result;
+ }
+
+ private Map<String, DataSource> createDataSourceMap() {
+ Map<String, DataSource> result = new HashMap<>();
+ result.put("demo_ds_0", DataSourceUtil.createDataSource("demo_ds_0"));
+ result.put("demo_ds_1", DataSourceUtil.createDataSource("demo_ds_1"));
+ return result;
+ }
+
+ private BroadcastRuleConfiguration createBroadcastRuleConfiguration() {
+ return new
BroadcastRuleConfiguration(Collections.singletonList("t_address"));
+ }
+}
+```
+
+## Related References
+
+- [Core Feature: Data Sharding](/en/features/sharding/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/single.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/single.cn.md
new file mode 100644
index 00000000000..4ca9001f011
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/single.cn.md
@@ -0,0 +1,35 @@
++++
+title = "单表"
+weight = 12
++++
+
+## 背景信息
+
+单表规则用于指定哪些单表需要被 ShardingSphere 管理，也可设置默认的单表数据源。
+
+## 参数解释
+
+类名称：org.apache.shardingsphere.single.api.config.SingleRuleConfiguration
+
+可配置属性：
+
+| *名称* | *数据类型* | *说明* | *默认值* |
+|-----------------------|----------------------|---------|-------|
+| tables (+) | Collection\<String\> | 单表规则列表 | - |
+| defaultDataSource (?) | String | 单表默认数据源 | - |
+
+## 操作步骤
+
+1. 初始化 SingleRuleConfiguration；
+2. 添加需要加载的单表，配置默认数据源。
+
+## 配置示例
+
+```java
+SingleRuleConfiguration ruleConfig = new SingleRuleConfiguration();
+ShardingSphereDataSourceFactory.createDataSource(createDataSourceMap(),
Arrays.asList(ruleConfig), new Properties());
+```
+
+## 相关参考
+
+- [单表](/cn/features/sharding/concept/#单表)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/single.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/single.en.md
new file mode 100644
index 00000000000..7cbd002b0e7
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/single.en.md
@@ -0,0 +1,35 @@
++++
+title = "Single Table"
+weight = 12
++++
+
+## Background
+
+Single rule is used to specify which single tables need to be managed by
ShardingSphere, or to set the default single table data source.
+
+## Parameters
+
+Class：org.apache.shardingsphere.single.api.config.SingleRuleConfiguration
+
+Attributes：
+
+| *name* | *DataType* | *Description*
| *Default Value* |
+|-----------------------|----------------------|----------------------------------|-----------------|
+| tables (+) | Collection\<String\> | single tables
| - |
+| defaultDataSource (?) | String | single table default data source | -
|
+
+## Procedure
+
+1. Initialize SingleRuleConfiguration;
+2. Add a single table to be loaded and configure the default data source.
+
+## Sample
+
+```java
+SingleRuleConfiguration ruleConfig = new SingleRuleConfiguration();
+ShardingSphereDataSourceFactory.createDataSource(createDataSourceMap(),
Arrays.asList(ruleConfig), new Properties());
+```
+
+## Related References
+
+- [Single Table](/en/features/sharding/concept/#single-table)
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 e286ff7eeb7..81607b29775 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
@@ -1,6 +1,6 @@
+++
title = "SQL 解析"
-weight = 7
+weight = 8
+++
## 背景信息
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 a32207d1b14..dacd52132a1 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
@@ -1,6 +1,6 @@
+++
title = "SQL Parser"
-weight = 7
+weight = 8
+++
## Background
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator.cn.md
index 0b4641ea05b..eb9d3b182dd 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator.cn.md
@@ -1,9 +1,13 @@
+++
title = "SQL 翻译"
-weight = 8
+weight = 9
+++
-## 配置入口
+## 背景信息
+
+通过 Java API 形式使用 SQL 翻译，可以方便得集成进入各种系统，灵活定制用户需求。
+
+## 参数解释
类名称：org.apache.shardingsphere.sqltranslator.api.config.SQLTranslatorRuleConfiguration
@@ -13,3 +17,18 @@ weight = 8
|-----------------------------------------|---------|-------------------------|
| type | String | SQL 翻译器类型 |
| useOriginalSQLWhenTranslatingFailed (?) | boolean | SQL 翻译失败是否使用原始 SQL 继续执行 |
+
+## 操作步骤
+
+1. 配置翻译类型 type
+2. 配置 useOriginalSQLWhenTranslatingFailed 参数，是否在 SQL 翻译失败后使用原始 SQL 继续执行
+
+## 配置示例
+
+```java
+SQLTranslatorRuleConfiguration ruleConfig = new
SQLTranslatorRuleConfiguration("Jooq", new Properties(), false);
+String translatedSQL = new SQLTranslatorRule(ruleConfig).translate();
+```
+
+## 相关参考
+- [YAML 配置：SQL
翻译](/cn/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator.en.md
index ab511b7b586..b78f1a0c2e3 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator.en.md
@@ -1,9 +1,13 @@
+++
title = "SQL Translator"
-weight = 8
+weight = 9
+++
-## Root Configuration
+## Background
+
+By using SQL translator in the form of Java API, you can easily integrate into
various systems and flexibly customize user requirements.
+
+## Parameters
Class:
org.apache.shardingsphere.sqltranslator.api.config.SQLTranslatorRuleConfiguration
@@ -13,3 +17,18 @@ Attributes:
|-----------------------------------------|------------|--------------------------------------------------|
| type | String | SQL translator type
|
| useOriginalSQLWhenTranslatingFailed (?) | boolean | Whether use original
SQL when translating failed |
+
+## Procedure
+
+1. Set SQL translator type.
+2. Set useOriginalSQLWhenTranslatingFailed to decide whether use original SQL
when translating failed.
+
+## Sample
+
+```java
+SQLTranslatorRuleConfiguration ruleConfig = new
SQLTranslatorRuleConfiguration("Jooq", new Properties(), false);
+String translatedSQL = new SQLTranslatorRule(ruleConfig).translate();
+```
+
+## Related References
+- [YAML Configuration: SQL
Translator](/en/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/transaction.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/transaction.cn.md
index af0718d756d..c7d48ef169f 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/transaction.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/transaction.cn.md
@@ -1,6 +1,6 @@
+++
title = "分布式事务"
-weight = 3
+weight = 4
+++
## 配置入口
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/transaction.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/transaction.en.md
index d2cae2491b8..fbb27e831bb 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/transaction.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/java-api/rules/transaction.en.md
@@ -1,6 +1,6 @@
+++
title = "Distributed Transaction"
-weight = 3
+weight = 4
+++
## Root Configuration
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator.cn.md
index b7b6c3da701..3193f9863ee 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator.cn.md
@@ -3,10 +3,30 @@ title = "SQL 翻译"
weight = 9
+++
-## 配置项说明
+## 背景信息
+
+SQL 翻译 YAML 配置方式具有可读性高，使用简单的特点。通过 YAML 文件的方式，用户可以将代码与配置分离，并且根据需要方便地修改配置文件。
+
+## 参数解释
```yaml
sqlTranslator:
type: # SQL 翻译器类型
useOriginalSQLWhenTranslatingFailed: # SQL 翻译失败是否使用原始 SQL 继续执行
```
+
+## 操作步骤
+
+1. 配置翻译类型 type
+2. 配置 useOriginalSQLWhenTranslatingFailed 参数，是否在 SQL 翻译失败后使用原始 SQL 继续执行
+
+## 配置示例
+
+```yaml
+sqlTranslator:
+ type: Jooq
+ useOriginalSQLWhenTranslatingFailed: true
+```
+
+## 相关参考
+- [JAVA API：SQL
翻译](/cn/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator.en.md
index a387dcd6426..0e1abd9d2bc 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/sql-translator.en.md
@@ -3,10 +3,29 @@ title = "SQL Translator"
weight = 9
+++
-## Configuration Item Explanation
+## Background
+
+The SQL translator 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
sqlTranslator:
type: # SQL translator type
useOriginalSQLWhenTranslatingFailed: # Whether use original SQL when
translating failed
```
+
+## Procedure
+1. Set SQL translator type.
+2. Set useOriginalSQLWhenTranslatingFailed to decide whether use original SQL
when translating failed.
+
+## Sample
+
+```yaml
+sqlTranslator:
+ type: Jooq
+ useOriginalSQLWhenTranslatingFailed: true
+```
+
+## Related References
+- [JAVA API: SQL
Translator](/en/user-manual/shardingsphere-jdbc/java-api/rules/sql-translator/)
