tristaZero commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r522913472
##########
File path: docs/document/content/features/sharding/principle/parse.en.md
##########
@@ -25,10 +25,56 @@ 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 users adopt `PreparedStatement` this SQL
pre-compilation method to improve performance. Currently, users can also use
ShardingSphere's SQL parsing engine independently to obtain AST and SQL
Statements for a variety of mainstream relational databases. In the future, the
SQL parsing engine will continue to provide powerful functions such as SQL
formatting and SQL templating.
+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 recommend that users adopt `PreparedStatement`
this SQL pre-compilation method to improve performance. Currently, users can
also use ShardingSphere's SQL parsing engine independently to obtain AST and
SQL Statements for a variety of mainstream relational databases. In the future,
the SQL parsing engine will continue to provide powerful functions such as SQL
formatting and SQL templating.
+
+### Features
+
+* Independent SQL parsing engine
+* Support multiple dialects
+
+| DB | Status |
+|----------|--------|
+|MySQL |supported|
+|PostgreSQL|supported|
+|SQLServer |supported|
+|Oracle |supported|
+|SQL92 |supported|
+
+* SQL format (developing)
+* SQL parameterize (developing)
+
+### Advantages
+The syntax rules can be easily expanded and modified by using `ANTLR`
+
+### 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)
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-sql-parser-mysql</artifactId>
+ <version>${project.version}</version>
+</dependency>
+```
+
+demo:
+
+1. Get AST
+
+```
+ParseTree tree = new SQLParserEngine(databaseType).parse(sql, false)
Review comment:
First, it is expected to give more explanation for all its parameters.
Plus, a list of possible values for `databaseType` is needed as well.
Second, another chapter, e.g., `2. Get different visited results` is also
necessary. We can provide other parsed results except for `AST`, which is just
a basic one. At least, `SQLStatement` may be an option for users currently, and
more wonderful features are ongoing, won't we?
##########
File path: docs/document/content/features/sharding/principle/parse.cn.md
##########
@@ -39,4 +41,46 @@ 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解析功能
+* 支持多种方言的SQL解析
+
+| 数据库 | 支持状态 |
+|----------|--------|
+|MySQL |支持，完善|
+|PostgreSQL|支持，完善|
+|SQLServer |支持 |
+|Oracle |支持 |
+|SQL92 |支持 |
+* 提供SQL格式化功能（开发中）
+* 提供SQL模板话功能（开发中）
+### 优点
+由于使用了 `ANTLR`， 可以非常方便的对语法规则进行扩充和修改
Review comment:
Could you move this point to the `Features` above? IMO, this is one
function of our parser as well.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
