You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by GitBox <gi...@apache.org> on 2020/11/11 12:13:23 UTC

[GitHub] [shardingsphere] jingshanglu opened a new pull request #8138: improve SQL Parser doc

jingshanglu opened a new pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138


   
   


----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] jingshanglu commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
jingshanglu commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r523922634



##########
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:
       Ok, i'll add some explanation for its parameters. 
   1. `SQLParserEngine` is thread-safe.
   2. There is no benchmark for this parser for the time being. It will come in the future.




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] tristaZero commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
tristaZero commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r523425976



##########
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:
       Hi @wu-sheng 
   1. Currently, SS will return the concrete SQLStatement, like `SelectStatement`, or `UpdateStatement`, which means you need some of `IF` code clips to get the corresponding SQL types.
   2. If you just wanna get a full table list of `DDL` and `DML` SQL, I guess the visitor result, `SQLStatement` (Not a  comprehensive AST) seems suffienct. No doubt, a test is needed in case.
   3. Yep, an LRU cache mechanism is embodied in SQL Parser. So, users do not need to do any other extra work.




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] codecov-io commented on pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
codecov-io commented on pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#issuecomment-727738120


   # [Codecov](https://codecov.io/gh/apache/shardingsphere/pull/8138?src=pr&el=h1) Report
   > Merging [#8138](https://codecov.io/gh/apache/shardingsphere/pull/8138?src=pr&el=desc) (4d3b3ff) into [master](https://codecov.io/gh/apache/shardingsphere/commit/cd192e5416649e50bb5cc1cdeb4023e89f83277e?el=desc) (cd192e5) will **increase** coverage by `0.06%`.
   > The diff coverage is `n/a`.
   
   [![Impacted file tree graph](https://codecov.io/gh/apache/shardingsphere/pull/8138/graphs/tree.svg?width=650&height=150&src=pr&token=ZvlXpWa7so)](https://codecov.io/gh/apache/shardingsphere/pull/8138?src=pr&el=tree)
   
   ```diff
   @@             Coverage Diff              @@
   ##             master    #8138      +/-   ##
   ============================================
   + Coverage     75.12%   75.19%   +0.06%     
   - Complexity      548      575      +27     
   ============================================
     Files          1450     1453       +3     
     Lines         22730    23190     +460     
     Branches       4057     4154      +97     
   ============================================
   + Hits          17077    17438     +361     
   - Misses         4539     4611      +72     
   - Partials       1114     1141      +27     
   ```
   
   
   | [Impacted Files](https://codecov.io/gh/apache/shardingsphere/pull/8138?src=pr&el=tree) | Coverage Δ | Complexity Δ | |
   |---|---|---|---|
   | [...e/encrypt/merge/dql/EncryptDQLResultDecorator.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtZmVhdHVyZXMvc2hhcmRpbmdzcGhlcmUtZW5jcnlwdC9zaGFyZGluZ3NwaGVyZS1lbmNyeXB0LW1lcmdlL3NyYy9tYWluL2phdmEvb3JnL2FwYWNoZS9zaGFyZGluZ3NwaGVyZS9lbmNyeXB0L21lcmdlL2RxbC9FbmNyeXB0RFFMUmVzdWx0RGVjb3JhdG9yLmphdmE=) | `66.66% <0.00%> (-33.34%)` | `0.00% <0.00%> (ø%)` | |
   | [...infra/rule/builder/ShardingSphereRulesBuilder.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtaW5mcmEvc2hhcmRpbmdzcGhlcmUtaW5mcmEtY29tbW9uL3NyYy9tYWluL2phdmEvb3JnL2FwYWNoZS9zaGFyZGluZ3NwaGVyZS9pbmZyYS9ydWxlL2J1aWxkZXIvU2hhcmRpbmdTcGhlcmVSdWxlc0J1aWxkZXIuamF2YQ==) | `72.72% <0.00%> (-27.28%)` | `0.00% <0.00%> (ø%)` | |
   | [...ypt/merge/dal/impl/EncryptColumnsMergedResult.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtZmVhdHVyZXMvc2hhcmRpbmdzcGhlcmUtZW5jcnlwdC9zaGFyZGluZ3NwaGVyZS1lbmNyeXB0LW1lcmdlL3NyYy9tYWluL2phdmEvb3JnL2FwYWNoZS9zaGFyZGluZ3NwaGVyZS9lbmNyeXB0L21lcmdlL2RhbC9pbXBsL0VuY3J5cHRDb2x1bW5zTWVyZ2VkUmVzdWx0LmphdmE=) | `71.42% <0.00%> (-18.82%)` | `0.00% <0.00%> (ø%)` | |
   | [...a/atomikos/manager/AtomikosTransactionManager.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtdHJhbnNhY3Rpb24vc2hhcmRpbmdzcGhlcmUtdHJhbnNhY3Rpb24tMnBjL3NoYXJkaW5nc3BoZXJlLXRyYW5zYWN0aW9uLXhhL3NoYXJkaW5nc3BoZXJlLXRyYW5zYWN0aW9uLXhhLWF0b21pa29zL3NyYy9tYWluL2phdmEvb3JnL2FwYWNoZS9zaGFyZGluZ3NwaGVyZS90cmFuc2FjdGlvbi94YS9hdG9taWtvcy9tYW5hZ2VyL0F0b21pa29zVHJhbnNhY3Rpb25NYW5hZ2VyLmphdmE=) | `83.33% <0.00%> (-16.67%)` | `1.00% <0.00%> (ø%)` | |
   | [...bitronix/manager/BitronixXATransactionManager.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtdHJhbnNhY3Rpb24vc2hhcmRpbmdzcGhlcmUtdHJhbnNhY3Rpb24tMnBjL3NoYXJkaW5nc3BoZXJlLXRyYW5zYWN0aW9uLXhhL3NoYXJkaW5nc3BoZXJlLXRyYW5zYWN0aW9uLXhhLWJpdHJvbml4L3NyYy9tYWluL2phdmEvb3JnL2FwYWNoZS9zaGFyZGluZ3NwaGVyZS90cmFuc2FjdGlvbi94YS9iaXRyb25peC9tYW5hZ2VyL0JpdHJvbml4WEFUcmFuc2FjdGlvbk1hbmFnZXIuamF2YQ==) | `76.47% <0.00%> (-16.39%)` | `1.00% <0.00%> (ø%)` | |
   | [...narayana/manager/NarayanaXATransactionManager.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtdHJhbnNhY3Rpb24vc2hhcmRpbmdzcGhlcmUtdHJhbnNhY3Rpb24tMnBjL3NoYXJkaW5nc3BoZXJlLXRyYW5zYWN0aW9uLXhhL3NoYXJkaW5nc3BoZXJlLXRyYW5zYWN0aW9uLXhhLW5hcmF5YW5hL3NyYy9tYWluL2phdmEvb3JnL2FwYWNoZS9zaGFyZGluZ3NwaGVyZS90cmFuc2FjdGlvbi94YS9uYXJheWFuYS9tYW5hZ2VyL05hcmF5YW5hWEFUcmFuc2FjdGlvbk1hbmFnZXIuamF2YQ==) | `86.36% <0.00%> (-13.64%)` | `1.00% <0.00%> (ø%)` | |
   | [...ingsphere/scaling/core/job/ShardingScalingJob.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtc2NhbGluZy9zaGFyZGluZ3NwaGVyZS1zY2FsaW5nLWNvcmUvc3JjL21haW4vamF2YS9vcmcvYXBhY2hlL3NoYXJkaW5nc3BoZXJlL3NjYWxpbmcvY29yZS9qb2IvU2hhcmRpbmdTY2FsaW5nSm9iLmphdmE=) | `90.90% <0.00%> (-9.10%)` | `0.00% <0.00%> (ø%)` | |
   | [...g/core/job/position/FinishedInventoryPosition.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtc2NhbGluZy9zaGFyZGluZ3NwaGVyZS1zY2FsaW5nLWNvcmUvc3JjL21haW4vamF2YS9vcmcvYXBhY2hlL3NoYXJkaW5nc3BoZXJlL3NjYWxpbmcvY29yZS9qb2IvcG9zaXRpb24vRmluaXNoZWRJbnZlbnRvcnlQb3NpdGlvbi5qYXZh) | `60.00% <0.00%> (-6.67%)` | `1.00% <0.00%> (+1.00%)` | :arrow_down: |
   | [...ore/job/position/PlaceholderInventoryPosition.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtc2NhbGluZy9zaGFyZGluZ3NwaGVyZS1zY2FsaW5nLWNvcmUvc3JjL21haW4vamF2YS9vcmcvYXBhY2hlL3NoYXJkaW5nc3BoZXJlL3NjYWxpbmcvY29yZS9qb2IvcG9zaXRpb24vUGxhY2Vob2xkZXJJbnZlbnRvcnlQb3NpdGlvbi5qYXZh) | `60.00% <0.00%> (-6.67%)` | `1.00% <0.00%> (+1.00%)` | :arrow_down: |
   | [...ql/dialect/handler/dml/DeleteStatementHandler.java](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree#diff-c2hhcmRpbmdzcGhlcmUtc3FsLXBhcnNlci9zaGFyZGluZ3NwaGVyZS1zcWwtcGFyc2VyLXN0YXRlbWVudC9zcmMvbWFpbi9qYXZhL29yZy9hcGFjaGUvc2hhcmRpbmdzcGhlcmUvc3FsL3BhcnNlci9zcWwvZGlhbGVjdC9oYW5kbGVyL2RtbC9EZWxldGVTdGF0ZW1lbnRIYW5kbGVyLmphdmE=) | `16.66% <0.00%> (-5.56%)` | `0.00% <0.00%> (ø%)` | |
   | ... and [157 more](https://codecov.io/gh/apache/shardingsphere/pull/8138/diff?src=pr&el=tree-more) | |
   
   ------
   
   [Continue to review full report at Codecov](https://codecov.io/gh/apache/shardingsphere/pull/8138?src=pr&el=continue).
   > **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
   > `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
   > Powered by [Codecov](https://codecov.io/gh/apache/shardingsphere/pull/8138?src=pr&el=footer). Last update [cd192e5...4d3b3ff](https://codecov.io/gh/apache/shardingsphere/pull/8138?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).
   


----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] tristaZero commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
tristaZero commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r524889284



##########
File path: docs/document/content/features/sharding/principle/parse.cn.md
##########
@@ -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 sqlFormarted = sqlVisitorEngine.visit(tree);

Review comment:
       `sqlFormarted` ?




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] wu-sheng commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
wu-sheng commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r522977479



##########
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:
       +1, Look forward to a simpler return value rather than a tree, maybe? From the SkyWalking analysis requirements, https://github.com/apache/skywalking/issues/5838, we need
   1. DML type, create/delete/update. Or it is a DDL.
   1. A listener mode or a way to iterate the table lists. I am not sure which way do you provide for now. 
   
   The basic idea is, SkyWalking as an APM, doesn't intend to do routing, sharding, or anything similar, we are planning to leverage this to get the basic profile of the executed SQL statements which were captured by the SkyWalking agents.
   
   Also, I remember there is a cache mechanism in the parser engine, do you have an LRU cache to keep memory safe? Or could I provide an implementation for the cache by following your interface?




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] wu-sheng commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
wu-sheng commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r523428916



##########
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:
       > If you just wanna get a full table list of DDL and DML SQL, I guess the visitor result, SQLStatement (Not a comprehensive AST) seems suffienct. No doubt, a test is needed in case.
   
   I have to iterate this object, right? 
   
   __
   2 more questions
   1. Whether `SQLParserEngine` is thread-safe? How to use it in the SkyWalking concurrent streaming process?
   1. Do you have a benchmark for the benchmark for this parser? 




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] tristaZero merged pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
tristaZero merged pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138


   


----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] wu-sheng commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
wu-sheng commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r522801191



##########
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`， 可以非常方便的对语法规则进行扩充和修改
+
+### 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>
+```
+
+例子
+
+1. 获取语法树
+
+```
+ParseTree tree = new SQLParserEngine(databaseType).parse(sql, false)

Review comment:
       Where could I find the ParseTree API?




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] wu-sheng commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
wu-sheng commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r522974085



##########
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`， 可以非常方便的对语法规则进行扩充和修改
+
+### 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>
+```
+
+例子
+
+1. 获取语法树
+
+```
+ParseTree tree = new SQLParserEngine(databaseType).parse(sql, false)

Review comment:
       I mean, do you intend to provide the APIs doc for the return type?




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] jingshanglu commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
jingshanglu commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r524932942



##########
File path: docs/document/content/features/sharding/principle/parse.cn.md
##########
@@ -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 sqlFormarted = sqlVisitorEngine.visit(tree);

Review comment:
       @tristaZero I'll change it.




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] tristaZero commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
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:
users@infra.apache.org

[GitHub] [shardingsphere] wu-sheng commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
wu-sheng commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r522800986



##########
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`， 可以非常方便的对语法规则进行扩充和修改
+
+### 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>

Review comment:
       Can we add all parsers? Would they conflict with each other?




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] tristaZero commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
tristaZero commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r524830968



##########
File path: docs/document/content/features/sharding/principle/parse.cn.md
##########
@@ -39,4 +41,78 @@ 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>
+```
+
+例子
+
+1. 获取语法树
+
+```
+/**
+     * 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); 
+```
+
+2. 获取SQLStatement
+
+```
+/**
+     * databaseType type:String 可能值 MySQL,Oracle，PostgreSQL，SQL92，SQLServer
+     * useCache type:boolean 是否使用缓存
+     * @return SQLStatement
+     */

Review comment:
       Line 100 is supposed to keep aligned with line 96.

##########
File path: docs/document/content/features/sharding/principle/parse.cn.md
##########
@@ -39,4 +41,78 @@ 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>
+```
+
+例子
+
+1. 获取语法树
+
+```
+/**
+     * 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); 
+```
+
+2. 获取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 sqlFormarted = sqlVisitorEngine.visit(tree);
+
+```
+
+3. SQL 格式化

Review comment:
       Since we did not include this feature in 5.0.0-alpha, please add (TODO) or remove this section.

##########
File path: docs/document/content/features/sharding/principle/parse.cn.md
##########
@@ -39,4 +41,78 @@ 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>
+```
+
+例子
+
+1. 获取语法树
+
+```
+/**
+     * 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); 
+```
+
+2. 获取SQLStatement

Review comment:
       The numbers 1, 2, 3  will confuse users that they have to operate them in ordinal. However, users can pick one of them once. Hence I suggest splitting them into 1  and 2/3 two sections, plus use `*` or `-` instead of the ordinals.




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] tristaZero commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
tristaZero commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r522907122



##########
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`， 可以非常方便的对语法规则进行扩充和修改
+
+### 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>

Review comment:
       Yep, you could, no conflict.




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] jingshanglu commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
jingshanglu commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r522819855



##########
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`， 可以非常方便的对语法规则进行扩充和修改
+
+### 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>
+```
+
+例子
+
+1. 获取语法树
+
+```
+ParseTree tree = new SQLParserEngine(databaseType).parse(sql, false)

Review comment:
       @wu-sheng 
   ![image](https://user-images.githubusercontent.com/16559542/99051467-605d8180-25d3-11eb-9b01-21964c8122f7.png)
   




----------------------------------------------------------------
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:
users@infra.apache.org

[GitHub] [shardingsphere] jingshanglu commented on a change in pull request #8138: improve SQL Parser doc

Posted by GitBox <gi...@apache.org>.
jingshanglu commented on a change in pull request #8138:
URL: https://github.com/apache/shardingsphere/pull/8138#discussion_r523914082



##########
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:
       Ok.




----------------------------------------------------------------
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:
users@infra.apache.org