DTStack · mumiao · May 8, 2025 · Jul 1, 2024 · Jul 5, 2024 · Aug 1, 2024
diff --git a/README-zh_CN.md b/README-zh_CN.md
@@ -356,6 +356,55 @@ console.log(sqlSlices)
 
 行列号信息不是必传的，如果传了行列号信息，那么收集到的实体中，如果实体位于对应行列号所在的语句下，那么实体的所属的语句对象上会带有 `isContainCaret` 标识，这在与自动补全功能结合时，可以帮助你快速筛选出需要的实体信息。
 
+
+### 获取语义上下文信息
+调用 SQL 实例上的 `getSemanticContextAtCaretPosition` 方法，传入 sql 文本和指定位置的行列号, 例如：
+```typescript
+import { HiveSQL } from 'dt-sql-parser';
+
+const hive = new HiveSQL();
+const sql = 'SELECT * FROM tb;';
+const pos = { lineNumber: 1, column: 18 }; // 'tb;' 的后面
+const semanticContext = hive.getSemanticContextAtCaretPosition(sql, pos);
+
+console.log(semanticContext);
+```
+
+*输出*
+
+```typescript
+/*
+{
+  isStatementBeginning: true,
+}
+*/
+```
+
+目前能收集到的语义上下文信息如下，如果有更多的需求，欢迎提[issue](https://github.com/DTStack/dt-sql-parser/issues)
+- `isStatementBeginning` 当前输入位置是否为一条语句的开头
+
+默认情况下，`isStatementBeginning` 的收集策略为`SqlSplitStrategy.STRICT`
+
+有两种可选策略:
+- `SqlSplitStrategy.STRICT` 严格策略, 仅以语句分隔符`;`作为上一条语句结束的标识
+- `SqlSplitStrategy.LOOSE` 宽松策略, 以语法解析树为基础分割SQL
+
+两种策略的差异：
+如输入SQL为
+```sql
+CREATE TABLE tb (id INT)
+
+SELECT
+```
+CREATE语句后未添加分号，那么当获取SELECT后的语义上下文时，
+在`SqlSplitStrategy.STRICT`策略下`isStatementBeginning` 为`false`, 因为CREATE语句未以分号结尾，那么会被认为这条语句尚未结束;
+在`SqlSplitStrategy.LOOSE`策略下`isStatementBeginning` 为`true`, 因为语法解析树中这条SQL被拆分成了CREATE独立语句与SELECT独立语句。
+
+可以通过第三个`options`参数设置策略:
+```typescript
+hive.getSemanticContextAtCaretPosition(sql, pos, { splitSqlStrategy: SqlSplitStrategy.LOOSE });
+```
+
 ### 其他 API
 
 - `createLexer` 创建一个 Antlr4 Lexer 实例并返回；

diff --git a/README.md b/README.md
@@ -357,6 +357,57 @@ Call the `getAllEntities` method on the SQL instance, and pass in the sql text a
 
 Position is not required, if the position is passed, then in the collected entities, if the entity is located under the statement where the corresponding position is located, then the statement object to which the entity belongs will be marked with `isContainCaret`, which can help you quickly filter out the required entities when combined with the code completion function.
 
+### Get semantic context information
+
+Call the `getSemanticContextAtCaretPosition` method on the SQL instance, passing in the sql text and the line and column numbers at the specified position, for example:
+
+```typescript
+import { HiveSQL } from 'dt-sql-parser';
+
+const hive = new HiveSQL();
+const sql = 'SELECT * FROM tb;';
+const pos = { lineNumber: 1, column: 18 }; // after 'tb;'
+const semanticContext = hive.getSemanticContextAtCaretPosition(sql, pos);
+
+console.log(semanticContext);
+```
+
+*output*
+
+```typescript
+/*
+{
+  isStatementBeginning: true,
+}
+*/
+```
+
+Currently, the semantic context information that can be collected is as follows. If there are more requirements, please submit an [issue](https://github.com/DTStack/dt-sql-parser/issues).
+
+- `isStatementBeginning` Whether the current input position is the beginning of a statement
+
+The **default strategy** for `isStatementBeginning` is `SqlSplitStrategy.STRICT`
+
+There are two optional strategies:
+- `SqlSplitStrategy.STRICT` Strict strategy, only the statement delimiter `;` is used as the identifier for the end of the previous statement
+- `SqlSplitStrategy.LOOSE` Loose strategy, based on the syntax parsing tree to split SQL
+
+The difference between the two strategies:
+For example, if the input SQL is:
+```sql
+CREATE TABLE tb (id INT)
+
+SELECT
+```
+In the `SqlSplitStrategy.STRICT` strategy, `isStatementBeginning` is `false`, because the CREATE statement is not terminated by a semicolon.
+
+In the `SqlSplitStrategy.LOOSE` strategy, `isStatementBeginning` is `true`, because the syntax parsing tree splits the SQL into two independent statements: CREATE and SELECT.
+
+You can set the strategy through the third `options` parameter:
+```typescript
+hive.getSemanticContextAtCaretPosition(sql, pos, { splitSqlStrategy: SqlSplitStrategy.LOOSE });
+```
+
 ### Other API
 
 - `createLexer` Create an instance of Antlr4 Lexer and return it;

diff --git a/benchmark/benchmark.config.ts b/benchmark/benchmark.config.ts
@@ -80,6 +80,11 @@ const testFiles: TestFile[] = [
         includes: ['flink'],
         testTypes: ['getSuggestionAtCaretPosition'],
     },
+    {
+        name: 'Collect Semantics',
+        sqlFileName: 'select.sql',
+        testTypes: ['getSemanticContextAtCaretPosition'],
+    },
 ];
 
 export default {

diff --git a/benchmark/data/params.json b/benchmark/data/params.json
@@ -6,5 +6,8 @@
     "suggestion_flink": {
         "getAllEntities": ["$sql", { "lineNumber": 1020, "column": 38 }],
         "getSuggestionAtCaretPosition": ["$sql", { "lineNumber": 1020, "column": 38 }]
+    },
+    "select": {
+        "getSemanticContextAtCaretPosition": ["$sql", { "lineNumber": 997, "column": 25 }]
     }
 }
diff --git a/benchmark_reports/cold_start/flink.benchmark.md b/benchmark_reports/cold_start/flink.benchmark.md
@@ -4,33 +4,34 @@
 FlinkSQL
 
 ### Report Time
-2024/9/9 19:55:03
+2024/12/18 14:50:08
 
 ### Device
-macOS 14.4.1
+macOS 15.0.1
 (8) arm64 Apple M1 Pro
 16.00 GB
 
 ### Version
 `nodejs`: v21.6.1
-`dt-sql-parser`: v4.0.2
+`dt-sql-parser`: v4.1.0-beta.0
 `antlr4-c3`: v3.3.7
 `antlr4ng`: v2.0.11
 
 ### Running Mode
 Cold Start
 
 ### Report
-| Benchmark Name |         Method Name        |SQL Rows|Average Time(ms)| 
-|----------------|----------------------------|--------|----------------| 
-|Query Collection|        getAllTokens        |  1015  |       227      | 
-|Query Collection|          validate          |  1015  |       221      | 
-| Insert Columns |        getAllTokens        |  1001  |       65       | 
-| Insert Columns |          validate          |  1001  |       65       | 
-|  Create Table  |        getAllTokens        |  1004  |       27       | 
-|  Create Table  |          validate          |  1004  |       26       | 
-|    Split SQL   |     splitSQLByStatement    |   999  |       52       | 
-|Collect Entities|       getAllEntities       |  1056  |       141      | 
-|   Suggestion   |getSuggestionAtCaretPosition|  1056  |       131      | 
+|  Benchmark Name |           Method Name           |SQL Rows|Average Time(ms)| 
+|-----------------|---------------------------------|--------|----------------| 
+| Query Collection|           getAllTokens          |  1015  |       257      | 
+| Query Collection|             validate            |  1015  |       277      | 
+|  Insert Columns |           getAllTokens          |  1001  |       66       | 
+|  Insert Columns |             validate            |  1001  |       67       | 
+|   Create Table  |           getAllTokens          |  1004  |       27       | 
+|   Create Table  |             validate            |  1004  |       28       | 
+|    Split SQL    |       splitSQLByStatement       |   999  |       53       | 
+| Collect Entities|          getAllEntities         |  1056  |       191      | 
+|    Suggestion   |   getSuggestionAtCaretPosition  |  1056  |       185      | 
+|Collect Semantics|getSemanticContextAtCaretPosition|  1015  |       247      | 
 
 
diff --git a/benchmark_reports/cold_start/hive.benchmark.md b/benchmark_reports/cold_start/hive.benchmark.md
@@ -4,35 +4,36 @@
 HiveSQL
 
 ### Report Time
-2024/9/9 19:55:03
+2024/12/18 14:50:08
 
 ### Device
-macOS 14.4.1
+macOS 15.0.1
 (8) arm64 Apple M1 Pro
 16.00 GB
 
 ### Version
 `nodejs`: v21.6.1
-`dt-sql-parser`: v4.0.2
+`dt-sql-parser`: v4.1.0-beta.0
 `antlr4-c3`: v3.3.7
 `antlr4ng`: v2.0.11
 
 ### Running Mode
 Cold Start
 
 ### Report
-| Benchmark Name |         Method Name        |SQL Rows|Average Time(ms)| 
-|----------------|----------------------------|--------|----------------| 
-|Query Collection|        getAllTokens        |  1015  |       185      | 
-|Query Collection|          validate          |  1015  |       179      | 
-|  Update Table  |        getAllTokens        |  1011  |       112      | 
-|  Update Table  |          validate          |  1011  |       109      | 
-| Insert Columns |        getAllTokens        |  1001  |       329      | 
-| Insert Columns |          validate          |  1001  |       329      | 
-|  Create Table  |        getAllTokens        |  1002  |       21       | 
-|  Create Table  |          validate          |  1002  |       20       | 
-|    Split SQL   |     splitSQLByStatement    |  1001  |       72       | 
-|Collect Entities|       getAllEntities       |  1066  |       106      | 
-|   Suggestion   |getSuggestionAtCaretPosition|  1066  |       100      | 
+|  Benchmark Name |           Method Name           |SQL Rows|Average Time(ms)| 
+|-----------------|---------------------------------|--------|----------------| 
+| Query Collection|           getAllTokens          |  1015  |       194      | 
+| Query Collection|             validate            |  1015  |       194      | 
+|   Update Table  |           getAllTokens          |  1011  |       126      | 
+|   Update Table  |             validate            |  1011  |       119      | 
+|  Insert Columns |           getAllTokens          |  1001  |       326      | 
+|  Insert Columns |             validate            |  1001  |       323      | 
+|   Create Table  |           getAllTokens          |  1002  |       21       | 
+|   Create Table  |             validate            |  1002  |       20       | 
+|    Split SQL    |       splitSQLByStatement       |  1001  |       71       | 
+| Collect Entities|          getAllEntities         |  1066  |       338      | 
+|    Suggestion   |   getSuggestionAtCaretPosition  |  1066  |       148      | 
+|Collect Semantics|getSemanticContextAtCaretPosition|  1015  |       201      | 
 
 
diff --git a/benchmark_reports/cold_start/impala.benchmark.md b/benchmark_reports/cold_start/impala.benchmark.md
@@ -4,35 +4,36 @@
 ImpalaSQL
 
 ### Report Time
-2024/9/9 19:55:03
+2024/12/18 14:50:08
 
 ### Device
-macOS 14.4.1
+macOS 15.0.1
 (8) arm64 Apple M1 Pro
 16.00 GB
 
 ### Version
 `nodejs`: v21.6.1
-`dt-sql-parser`: v4.0.2
+`dt-sql-parser`: v4.1.0-beta.0
 `antlr4-c3`: v3.3.7
 `antlr4ng`: v2.0.11
 
 ### Running Mode
 Cold Start
 
 ### Report
-| Benchmark Name |         Method Name        |SQL Rows|Average Time(ms)| 
-|----------------|----------------------------|--------|----------------| 
-|Query Collection|        getAllTokens        |  1015  |       71       | 
-|Query Collection|          validate          |  1015  |       71       | 
-|  Update Table  |        getAllTokens        |  1011  |       113      | 
-|  Update Table  |          validate          |  1011  |       108      | 
-| Insert Columns |        getAllTokens        |  1001  |       208      | 
-| Insert Columns |          validate          |  1001  |       213      | 
-|  Create Table  |        getAllTokens        |  1002  |       23       | 
-|  Create Table  |          validate          |  1002  |       23       | 
-|    Split SQL   |     splitSQLByStatement    |  1001  |       65       | 
-|Collect Entities|       getAllEntities       |  1066  |       82       | 
-|   Suggestion   |getSuggestionAtCaretPosition|  1066  |       83       | 
+|  Benchmark Name |           Method Name           |SQL Rows|Average Time(ms)| 
+|-----------------|---------------------------------|--------|----------------| 
+| Query Collection|           getAllTokens          |  1015  |       77       | 
+| Query Collection|             validate            |  1015  |       72       | 
+|   Update Table  |           getAllTokens          |  1011  |       120      | 
+|   Update Table  |             validate            |  1011  |       121      | 
+|  Insert Columns |           getAllTokens          |  1001  |       218      | 
+|  Insert Columns |             validate            |  1001  |       217      | 
+|   Create Table  |           getAllTokens          |  1002  |       25       | 
+|   Create Table  |             validate            |  1002  |       25       | 
+|    Split SQL    |       splitSQLByStatement       |  1001  |       67       | 
+| Collect Entities|          getAllEntities         |  1066  |       93       | 
+|    Suggestion   |   getSuggestionAtCaretPosition  |  1066  |       101      | 
+|Collect Semantics|getSemanticContextAtCaretPosition|  1015  |       80       | 
 
 
diff --git a/benchmark_reports/cold_start/mysql.benchmark.md b/benchmark_reports/cold_start/mysql.benchmark.md
@@ -4,35 +4,36 @@
 MySQL
 
 ### Report Time
-2024/9/9 19:55:03
+2024/12/18 14:50:08
 
 ### Device
-macOS 14.4.1
+macOS 15.0.1
 (8) arm64 Apple M1 Pro
 16.00 GB
 
 ### Version
 `nodejs`: v21.6.1
-`dt-sql-parser`: v4.0.2
+`dt-sql-parser`: v4.1.0-beta.0
 `antlr4-c3`: v3.3.7
 `antlr4ng`: v2.0.11
 
 ### Running Mode
 Cold Start
 
 ### Report
-| Benchmark Name |         Method Name        |SQL Rows|Average Time(ms)| 
-|----------------|----------------------------|--------|----------------| 
-|Query Collection|        getAllTokens        |  1015  |      1281      | 
-|Query Collection|          validate          |  1015  |      1254      | 
-|  Update Table  |        getAllTokens        |  1011  |       876      | 
-|  Update Table  |          validate          |  1011  |       842      | 
-| Insert Columns |        getAllTokens        |  1001  |       261      | 
-| Insert Columns |          validate          |  1001  |       266      | 
-|  Create Table  |        getAllTokens        |  1002  |       48       | 
-|  Create Table  |          validate          |  1002  |       45       | 
-|    Split SQL   |     splitSQLByStatement    |  1001  |       287      | 
-|Collect Entities|       getAllEntities       |  1066  |       474      | 
-|   Suggestion   |getSuggestionAtCaretPosition|  1066  |       462      | 
+|  Benchmark Name |           Method Name           |SQL Rows|Average Time(ms)| 
+|-----------------|---------------------------------|--------|----------------| 
+| Query Collection|           getAllTokens          |  1015  |      1339      | 
+| Query Collection|             validate            |  1015  |      1305      | 
+|   Update Table  |           getAllTokens          |  1011  |       860      | 
+|   Update Table  |             validate            |  1011  |       898      | 
+|  Insert Columns |           getAllTokens          |  1001  |       282      | 
+|  Insert Columns |             validate            |  1001  |       284      | 
+|   Create Table  |           getAllTokens          |  1002  |       48       | 
+|   Create Table  |             validate            |  1002  |       50       | 
+|    Split SQL    |       splitSQLByStatement       |  1001  |       305      | 
+| Collect Entities|          getAllEntities         |  1066  |       653      | 
+|    Suggestion   |   getSuggestionAtCaretPosition  |  1066  |       637      | 
+|Collect Semantics|getSemanticContextAtCaretPosition|  1015  |      1418      | 
 
 
diff --git a/benchmark_reports/cold_start/postgresql.benchmark.md b/benchmark_reports/cold_start/postgresql.benchmark.md
@@ -4,35 +4,36 @@
 PostgreSQL
 
 ### Report Time
-2024/9/9 19:55:03
+2024/12/18 14:50:08
 
 ### Device
-macOS 14.4.1
+macOS 15.0.1
 (8) arm64 Apple M1 Pro
 16.00 GB
 
 ### Version
 `nodejs`: v21.6.1
-`dt-sql-parser`: v4.0.2
+`dt-sql-parser`: v4.1.0-beta.0
 `antlr4-c3`: v3.3.7
 `antlr4ng`: v2.0.11
 
 ### Running Mode
 Cold Start
 
 ### Report
-| Benchmark Name |         Method Name        |SQL Rows|Average Time(ms)| 
-|----------------|----------------------------|--------|----------------| 
-|Query Collection|        getAllTokens        |  1015  |      1086      | 
-|Query Collection|          validate          |  1015  |      1078      | 
-|  Update Table  |        getAllTokens        |  1011  |      1193      | 
-|  Update Table  |          validate          |  1011  |      1183      | 
-| Insert Columns |        getAllTokens        |  1001  |       539      | 
-| Insert Columns |          validate          |  1001  |       565      | 
-|  Create Table  |        getAllTokens        |  1002  |       294      | 
-|  Create Table  |          validate          |  1002  |       275      | 
-|    Split SQL   |     splitSQLByStatement    |  1001  |       597      | 
-|Collect Entities|       getAllEntities       |  1066  |       797      | 
-|   Suggestion   |getSuggestionAtCaretPosition|  1066  |       776      | 
+|  Benchmark Name |           Method Name           |SQL Rows|Average Time(ms)| 
+|-----------------|---------------------------------|--------|----------------| 
+| Query Collection|           getAllTokens          |  1015  |      1008      | 
+| Query Collection|             validate            |  1015  |       955      | 
+|   Update Table  |           getAllTokens          |  1011  |       941      | 
+|   Update Table  |             validate            |  1011  |       936      | 
+|  Insert Columns |           getAllTokens          |  1001  |       534      | 
+|  Insert Columns |             validate            |  1001  |       547      | 
+|   Create Table  |           getAllTokens          |  1002  |       288      | 
+|   Create Table  |             validate            |  1002  |       288      | 
+|    Split SQL    |       splitSQLByStatement       |  1001  |       522      | 
+| Collect Entities|          getAllEntities         |  1066  |       744      | 
+|    Suggestion   |   getSuggestionAtCaretPosition  |  1066  |       719      | 
+|Collect Semantics|getSemanticContextAtCaretPosition|  1015  |       941      |