This is an automated email from the ASF dual-hosted git repository.
panjuan 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 72229a4 improve SQL Parser doc (#8138)
72229a4 is described below
commit 72229a4c8a3d3fbf08fa92c6ccec136746188143
Author: JingShang Lu <[email protected]>
AuthorDate: Wed Nov 18 11:12:45 2020 +0800
improve SQL Parser doc (#8138)
* improve SQL Parser doc
* fix
* fix
* fix
* fix
---
.../features/sharding/principle/parse.cn.md | 69 +++++++++++++++++++++-
.../features/sharding/principle/parse.en.md | 65 +++++++++++++++++++-
2 files changed, 130 insertions(+), 4 deletions(-)
diff --git a/docs/document/content/features/sharding/principle/parse.cn.md
b/docs/document/content/features/sharding/principle/parse.cn.md
index 6c9e429..63bd9cb 100644
--- a/docs/document/content/features/sharding/principle/parse.cn.md
+++ b/docs/document/content/features/sharding/principle/parse.cn.md
@@ -10,7 +10,7 @@ weight = 1
解析过程分为词法解析和语法解析。
词法解析器用于将 SQL 拆解为不可再分的原子符号，称为 Token。并根据不同数据库方言所提供的字典，将其归类为关键字，表达式，字面量和操作符。
-再使用语法解析器将 SQL 转换为抽象语法树。
+再使用语法解析器将 词法解析器的输出 转换为抽象语法树。
例如，以下 SQL：
@@ -24,13 +24,15 @@ SELECT id, name FROM t_user WHERE status = 'ACTIVE' AND age
> 18
为了便于理解，抽象语法树中的关键字的 Token 用绿色表示，变量的 Token 用红色表示，灰色表示需要进一步拆分。
-最后，通过对抽象语法树的遍历去提炼分片所需的上下文，并标记有可能需要改写的位置。
+最后，通过`visitor`对抽象语法树遍历构造域模型，通过域模型(`SQLStatement`)去提炼分片所需的上下文，并标记有可能需要改写的位置。
供分片使用的解析上下文包含查询选择项（Select Items）、表信息（Table）、分片条件（Sharding
Condition）、自增主键信息（Auto increment Primary Key）、排序信息（Order By）、分组信息（Group
By）以及分页信息（Limit、Rownum、Top）。
SQL 的一次解析过程是不可逆的，一个个 Token 按 SQL 原本的顺序依次进行解析，性能很高。
考虑到各种数据库 SQL 方言的异同，在解析模块提供了各类数据库的 SQL 方言字典。
## SQL 解析引擎
+### 历史
+
SQL 解析作为分库分表类产品的核心，其性能和兼容性是最重要的衡量指标。
ShardingSphere 的 SQL 解析器经历了 3 代产品的更新迭代。
@@ -39,4 +41,65 @@ ShardingSphere 的 SQL 解析器经历了 3 代产品的更新迭代。
第二代 SQL 解析器从 1.5.x 版本开始，ShardingSphere 采用完全自研的 SQL 解析引擎。
由于目的不同，ShardingSphere 并不需要将 SQL 转为一颗完全的抽象语法树，也无需通过访问器模式进行二次遍历。它采用对 SQL
`半理解`的方式，仅提炼数据分片需要关注的上下文，因此 SQL 解析的性能和兼容性得到了进一步的提高。
-第三代 SQL 解析器从 3.0.x 版本开始，尝试使用 ANTLR 作为 SQL 解析引擎，并采用 Visit 的方式从 AST 中获取 SQL
Statement。从5.0.x 版本开始，解析引擎的架构已完成重构调整，同时通过将第一次解析的得到的 AST 放入缓存，方便下次直接获取相同
SQL的解析结果，来提高解析效率。 因此我们建议用户采用 `PreparedStatement` 这种 SQL
预编译的方式来提升性能。当前，用户还可以独立使用 ShardingSphere 的 SQL 解析引擎，获得多款主流关系型数据库的 AST 及 SQL
Statement。 未来，SQL 解析引擎将继续提供 SQL 格式化、 SQL 模板化等强大的功能。
+第三代 SQL 解析器从 3.0.x 版本开始，尝试使用 ANTLR 作为 SQL 解析引擎 的生成器，并采用 Visit 的方式从 AST 中获取 SQL
Statement。从5.0.x 版本开始，解析引擎的架构已完成重构调整，同时通过将第一次解析的得到的 AST 放入缓存，方便下次直接获取相同
SQL的解析结果，来提高解析效率。 因此我们建议用户采用 `PreparedStatement` 这种 SQL 预编译的方式来提升性能。
+
+### 功能点
+
+* 提供独立的SQL解析功能
+* 可以非常方便的对语法规则进行扩充和修改(使用了`ANTLR`)
+* 支持多种方言的SQL解析
+
+| 数据库 | 支持状态 |
+|----------|--------|
+|MySQL |支持，完善|
+|PostgreSQL|支持，完善|
+|SQLServer |支持 |
+|Oracle |支持 |
+|SQL92 |支持 |
+* 提供SQL格式化功能（开发中）
+* 提供SQL模板话功能（开发中）
+
+### API使用
+
+引入Maven依赖
+```
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-sql-parser-engine</artifactId>
+ <version>${project.version}</version>
+</dependency>
+// 根据需要引入指定方言的解析模块（以MySQL为例）,可以添加所有支持的方言，也可以只添加使用到的
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-sql-parser-mysql</artifactId>
+ <version>${project.version}</version>
+</dependency>
+```
+
+例子
+
+- 获取语法树
+
+```
+/**
+ * databaseType type:String 可能值 MySQL,Oracle，PostgreSQL，SQL92，SQLServer
+ * sql type:String 解析的SQL
+ * useCache type:boolean 是否使用缓存
+ * @return parse tree
+ */
+ParseTree tree = new SQLParserEngine(databaseType).parse(sql, useCache);
+```
+
+- 获取SQLStatement
+
+```
+/**
+ * databaseType type:String 可能值 MySQL,Oracle，PostgreSQL，SQL92，SQLServer
+ * useCache type:boolean 是否使用缓存
+ * @return SQLStatement
+ */
+ParseTree tree = new SQLParserEngine(databaseType).parse(sql, useCache);
+SQLVisitorEngine sqlVisitorEngine = new SQLVisitorEngine(databaseType,
"STATEMENT");
+SQLStatement sqlStatement = sqlVisitorEngine.visit(tree);
+
+```
diff --git a/docs/document/content/features/sharding/principle/parse.en.md
b/docs/document/content/features/sharding/principle/parse.en.md
index 40af146..e4d4ed3 100644
--- a/docs/document/content/features/sharding/principle/parse.en.md
+++ b/docs/document/content/features/sharding/principle/parse.en.md
@@ -25,10 +25,73 @@ At last, through traversing the abstract syntax tree, the
context needed by shar
## SQL Parser
+### History
+
As the core of database sharding and table sharding, SQL parser takes the
performance and compatibility as its most important index. ShardingSphere SQL
parser has undergone the upgrade and iteration of 3 generations of products.
To pursue good performance and quick achievement, the first generation of SQL
parser uses `Druid` before 1.4.x version. As tested in practice, its
performance exceeds other parsers a lot.
The second generation of SQL parsing engine begins from 1.5.x version,
ShardingSphere has adopted fully self-developed parsing engine ever since. Due
to different purposes, ShardingSphere does not need to transform SQL into a
totally abstract syntax tree or traverse twice through visitor. Using `half
parsing` method, it only extracts the context required by data sharding, so the
performance and compatibility of SQL parsing is further improved.
-The third generation of SQL parsing engine begins from 3.0.x version.
ShardingSphere tries to adopts ANTLR as the SQL parsing engine, and uses Visit
to obtain SQL Statement from AST. Starting from version 5.0.x, the architecture
of the parsing engine has been refactored. At the same time, it is convenient
to directly obtain the parsing results of the same SQL to improve parsing
efficiency by putting the AST obtained from the first parsing into the cache.
Therefore, we recommend that user [...]
+The third generation of SQL parsing engine begins from 3.0.x version.
ShardingSphere tries to adopts ANTLR as a generator for the SQL parsing engine,
and uses Visit to obtain SQL Statement from AST. Starting from version 5.0.x,
the architecture of the parsing engine has been refactored. At the same time,
it is convenient to directly obtain the parsing results of the same SQL to
improve parsing efficiency by putting the AST obtained from the first parsing
into the cache. Therefore, we rec [...]
+
+### Features
+
+* Independent SQL parsing engine
+* The syntax rules can be easily expanded and modified (using `ANTLR`)
+* Support multiple dialects
+
+| DB | Status |
+|----------|--------|
+|MySQL |supported|
+|PostgreSQL|supported|
+|SQLServer |supported|
+|Oracle |supported|
+|SQL92 |supported|
+
+* SQL format (developing)
+* SQL parameterize (developing)
+
+### API Usage
+
+Maven config
+```
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-sql-parser-engine</artifactId>
+ <version>${project.version}</version>
+</dependency>
+// According to the needs, introduce the parsing module of the specified
dialect (take MySQL as an example), you can add all the supported dialects, or
just what you need
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-sql-parser-mysql</artifactId>
+ <version>${project.version}</version>
+</dependency>
+```
+
+demo:
+
+- Get AST
+
+```
+/**
+ * databaseType type:String values: MySQL,Oracle，PostgreSQL，SQL92，SQLServer
+ * sql type:String SQL to be parsed
+ * useCache type:boolean whether use cache
+ * @return parse tree
+ */
+ParseTree tree = new SQLParserEngine(databaseType).parse(sql, useCache)
+```
+
+- GET SQLStatement
+
+```
+/**
+ * databaseType type:String values: MySQL,Oracle，PostgreSQL，SQL92，SQLServer
+ * useCache type:boolean whether use cache
+ * @return SQLStatement
+ */
+ParseTree tree = new SQLParserEngine(databaseType).parse(sql, useCache);
+SQLVisitorEngine sqlVisitorEngine = new SQLVisitorEngine(databaseType,
"STATEMENT");
+SQLStatement sqlStatement = sqlVisitorEngine.visit(tree);
+```
