oushu/lava-oushudb-dt-sql-parser
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: improve and update README

Browse Source
This commit is contained in:
hayden 2023-10-20 17:46:12 +08:00 committed by Hayden
parent 970bf4ee84
commit e494e00e68
2 changed files with 18 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
README-zh_CN.md
View File

@ -53,7 +53,7 @@ yarn add dt-sql-parser
<br/> <br/>
## 使用 ## 使用
在开始使用前，需要先了解基本的使用方式。`dt-sql-parser` 为不同类型的 SQL分别提供相应的 SQL Parser 类： 在开始使用前，需要先了解基本用法。`dt-sql-parser` 为不同类型的 SQL 分别提供相应的 SQL Parser 类：
```javascript ```javascript
import { GenericSQL, FlinkSQL, SparkSQL, HiveSQL, PLSQL, PostgresSQL, TrinoSQL } from 'dt-sql-parser'; import { GenericSQL, FlinkSQL, SparkSQL, HiveSQL, PLSQL, PostgresSQL, TrinoSQL } from 'dt-sql-parser';
``` ```
@ -65,8 +65,6 @@ const parser = new GenericSQL();
下文中的使用示例将使用 `GenericSQL`，其他 SQL 类型的 Parser 使用方式与`GenericSQL` 相同。 下文中的使用示例将使用 `GenericSQL`，其他 SQL 类型的 Parser 使用方式与`GenericSQL` 相同。
<br/>
### 语法校验（Syntax Validation） ### 语法校验（Syntax Validation）
```javascript ```javascript
import { GenericSQL } from 'dt-sql-parser'; import { GenericSQL } from 'dt-sql-parser';
@ -112,8 +110,6 @@ console.log(errors);
先实例化 Parser 对象，然后使用 `validate` 方法对 SQL 语句进行校验，如果校验失败，则返回一个包含 `error` 信息的数组。 先实例化 Parser 对象，然后使用 `validate` 方法对 SQL 语句进行校验，如果校验失败，则返回一个包含 `error` 信息的数组。
<br/>
### 词法分析（Tokenizer） ### 词法分析（Tokenizer）
必要场景下，可单独对 SQL 语句进行词法分析，获取所有的 Tokens 对象： 必要场景下，可单独对 SQL 语句进行词法分析，获取所有的 Tokens 对象：
@ -143,8 +139,6 @@ console.log(tokens)
*/ */
``` ```
<br/>
### 访问者模式（Visitor） ### 访问者模式（Visitor）
使用 Visitor 模式访问 AST 中的指定节点 使用 Visitor 模式访问 AST 中的指定节点
@ -180,8 +174,6 @@ TableName user1
> 提示：使用 Visitor 模式时，节点的方法名称可以在对应 SQL 目录下的 Visitor 文件中查找 > 提示：使用 Visitor 模式时，节点的方法名称可以在对应 SQL 目录下的 Visitor 文件中查找
<br/>
### 监听器（Listener） ### 监听器（Listener）
Listener 模式，利用 [ANTLR4](https://github.com/antlr/antlr4) 提供的 `ParseTreeWalker` 对象遍历 AST，进入各个节点时调用对应的方法。 Listener 模式，利用 [ANTLR4](https://github.com/antlr/antlr4) 提供的 `ParseTreeWalker` 对象遍历 AST，进入各个节点时调用对应的方法。
@ -215,8 +207,6 @@ TableName user1
> 提示：使用 Listener 模式时，节点的方法名称可以在对应 SQL 目录下的 Listener 文件中查找 > 提示：使用 Listener 模式时，节点的方法名称可以在对应 SQL 目录下的 Listener 文件中查找
<br/>
### SQL 按语句切割 ### SQL 按语句切割
以 `FlinkSQL` 为例： 以 `FlinkSQL` 为例：
```javascript ```javascript
@ -251,9 +241,7 @@ console.log(sqlSlices)
``` ```
<br/> ### 自动补全（Code Completion）
### 自动补全（Auto Complete）
在 sql 的指定位置上获取自动补全信息，以 `FlinkSQL` 为例： 在 sql 的指定位置上获取自动补全信息，以 `FlinkSQL` 为例：
调用 `getSuggestionAtCaretPosition` 方法，传入 sql 内容和需要自动补全的位置的行列号。 调用 `getSuggestionAtCaretPosition` 方法，传入 sql 内容和需要自动补全的位置的行列号。
@ -312,8 +300,6 @@ console.log(sqlSlices)
``` ```
语法相关自动补全信息返回一个数组，数组中每一项代表该位置可以填写什么语法，比如上例中的输出结果代表该位置可以填写**表名**或者**视图名称**。其中 `syntaxContextType` 是可以补全的语法类型，`wordRanges` 则是已经填写的内容。 语法相关自动补全信息返回一个数组，数组中每一项代表该位置可以填写什么语法，比如上例中的输出结果代表该位置可以填写**表名**或者**视图名称**。其中 `syntaxContextType` 是可以补全的语法类型，`wordRanges` 则是已经填写的内容。
<br/>
### 其他 API ### 其他 API
- `createLexer` 创建一个 Antlr4 Lexer 实例并返回； - `createLexer` 创建一个 Antlr4 Lexer 实例并返回；

44
README.md
View File

@ -15,7 +15,7 @@ English | [简体中文](./README-zh_CN.md)
dt-sql-parser is a **SQL Parser** project built with [ANTLR4](https://github.com/antlr/antlr4), and it's mainly for the **BigData** domain. The [ANTLR4](https://github.com/antlr/antlr4) generated the basic Parser, Visitor, and Listener, so it's easy to complete the **syntax validation**, **tokenizer**, **traverse** the AST, and so on features. dt-sql-parser is a **SQL Parser** project built with [ANTLR4](https://github.com/antlr/antlr4), and it's mainly for the **BigData** domain. The [ANTLR4](https://github.com/antlr/antlr4) generated the basic Parser, Visitor, and Listener, so it's easy to complete the **syntax validation**, **tokenizer**, **traverse** the AST, and so on features.
Besides, it provides some helper methods, like **split** SQL, and **Auto-Complete**. Additionally, it provides auxiliary functions such as SQL splitting and Auto-Complete.
**Supported SQL**: **Supported SQL**:
@ -27,7 +27,7 @@ Besides, it provides some helper methods, like **split** SQL, and **Auto-Complet
- PostgreSQL - PostgreSQL
- Trino SQL - Trino SQL
**Supported helper methods** **Supported auxiliary methods**
| SQL Type | SQL Split | Auto-Complete | | SQL Type | SQL Split | Auto-Complete |
| ----------- | -------- | -------- | | ----------- | -------- | -------- |
@ -63,19 +63,18 @@ yarn add dt-sql-parser
<br/> <br/>
## Usage ## Usage
Before you get started, you need to understand the basics of how to use it. `dt-sql-parser` provides SQL parser classes for different types of supported SQL: We recommend learning the Fundamentals usage before continuing. The dt-sql-parser library provides SQL Parser classes for different types of SQL.
```javascript ```javascript
import { GenericSQL, FlinkSQL, SparkSQL, HiveSQL, PLSQL, PostgresSQL, TrinoSQL } from 'dt-sql-parser'; import { GenericSQL, FlinkSQL, SparkSQL, HiveSQL, PLSQL, PostgresSQL, TrinoSQL } from 'dt-sql-parser';
``` ```
Before using syntax validation, autocompletion, and other method, you need to instantiate the Parser of the corresponding SQL type, taking `GenericSQL` as an example: Before employing syntax validation, code completion, and other features, it is necessary to instantiate the Parser of the relevant SQL type.
For instance, one can consider using `GenericSQL` as an example:
```javascript ```javascript
const parser = new GenericSQL(); const parser = new GenericSQL();
``` ```
The usage examples below will use `GenericSQL`, and Parser for other SQL types will be used in the same way as `GenericSQL`. The following usage examples will utilize the `GenericSQL`, and the Parser for other SQL types will be employed in a similar manner as `GenericSQL`.
<br/>
### Syntax Validation ### Syntax Validation
```javascript ```javascript
@ -123,8 +122,6 @@ Output:
We instanced a Parser object, and use the **validate** method to check the SQL syntax, if failed We instanced a Parser object, and use the **validate** method to check the SQL syntax, if failed
returns an array object includes **error** message. returns an array object includes **error** message.
<br/>
### Tokenizer ### Tokenizer
Get all **tokens** by the Parser: Get all **tokens** by the Parser:
@ -154,8 +151,6 @@ console.log(tokens)
*/ */
``` ```
<br/>
### Visitor ### Visitor
Traverse the tree node by the Visitor: Traverse the tree node by the Visitor:
@ -192,8 +187,6 @@ TableName user1
> Tips: The node's method name can be found in the Visitor file under the corresponding SQL directory > Tips: The node's method name can be found in the Visitor file under the corresponding SQL directory
<br/>
### Listener ### Listener
Access the specified node in the AST by the Listener Access the specified node in the AST by the Listener
@ -228,9 +221,7 @@ TableName user1
> Tips: The node's method name can be found in the Listener file under the corresponding SQL directory > Tips: The node's method name can be found in the Listener file under the corresponding SQL directory
<br/> ### Splitting SQL statements
### Split sql by statement
Take `FlinkSQL` as an example: Take `FlinkSQL` as an example:
```javascript ```javascript
import { FlinkSQL } from 'dt-sql-parser'; import { FlinkSQL } from 'dt-sql-parser';
@ -264,13 +255,12 @@ console.log(sqlSlices)
``` ```
<br/> ### Code Completion
Obtaining autocomplete information at a specified position in SQL.
We can refer to the example of using `FlinkSQL`.
### Auto Complete Invoke the `getSuggestionAtCaretPosition` method, pass the SQL content and the row and column numbers indicating the position where auto-completion is desired.
Get the autocomplete information in the specified position of sql, using `FlinkSQL` as an example: + keyword candidates list
Call the `getSuggestionAtCaretPosition` method, passing in the SQL content and the row and column numbers of the position that need to be autocompleted.
+ Get a list of keyword candidates
```javascript ```javascript
import { FlinkSQL } from 'dt-sql-parser'; import { FlinkSQL } from 'dt-sql-parser';
@ -284,7 +274,7 @@ Call the `getSuggestionAtCaretPosition` method, passing in the SQL content and t
[ 'CATALOG', 'FUNCTION', 'TEMPORARY', 'VIEW', 'DATABASE', 'TABLE' ] [ 'CATALOG', 'FUNCTION', 'TEMPORARY', 'VIEW', 'DATABASE', 'TABLE' ]
*/ */
``` ```
+ Gets syntax-related autocompletion information + Obtaining information related to grammar completion
```javascript ```javascript
const parser = new FlinkSQL(); const parser = new FlinkSQL();
const sql = 'SELECT * FROM tb'; const sql = 'SELECT * FROM tb';
@ -323,14 +313,12 @@ Call the `getSuggestionAtCaretPosition` method, passing in the SQL content and t
] ]
*/ */
``` ```
Syntax-related autocomplete information returns an array, and each item in the array represents what syntax can be filled in at that position, such as the output result in the above example represents that the position can be filled in **table name** or **view name**. The `syntaxContextType` is a syntax type that can be completed, and `wordRanges` is what has been filled in. The grammar-related autocomplete information returns an array, where each item represents what grammar can be filled in at that position. For example, the output in the above example represents that the position can be filled with either a **table name** or **a view name**. In this case, `syntaxContextType` represents the type of grammar that can be completed, and `wordRanges` represents the content that has already been filled.
<br/>
### Other API ### Other API
- `createLexer` Create an instance of Antlr4 Lexer and return; - `createLexer` Create an instance of Antlr4 Lexer and return it;
- `createParser` Create an instance of Antlr4 parser and return; - `createParser` Create an instance of Antlr4 parser and return it;
- `parse` Parses the input SQL and returns the parse tree; - `parse` Parses the input SQL and returns the parse tree;
<br/> <br/>