docs: rewrite syntax rules for query (#3609)

we're a simplified version of BigQuery SQL: https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax
4paradigm · Nov 24, 2023 · 17b166b · 17b166b
1 parent 7d89892
commit 17b166b
Show file tree

Hide file tree

Showing 10 changed files with 153 additions and 208 deletions.
diff --git a/docs/zh/openmldb_sql/dql/GROUP_BY_CLAUSE.md b/docs/zh/openmldb_sql/dql/GROUP_BY_CLAUSE.md
@@ -2,9 +2,9 @@
 
 ## Syntax
 
-```SQL
-GroupByClause
-         ::= 'GROUP' 'BY' ByList
+```yacc
+group_by_clause:
+  GROUP BY group_by_specification
 ```
 
 ## SQL语句模版

diff --git a/docs/zh/openmldb_sql/dql/HAVING_CLAUSE.md b/docs/zh/openmldb_sql/dql/HAVING_CLAUSE.md
@@ -4,9 +4,9 @@ Having 子句与 Where 子句作用类似.Having 子句过滤 GroupBy 后的各
 
 ## Syntax
 
-```
-HavingClause
-         ::= 'HAVING' Expression 
+```yacc
+having_clause
+  HAVING bool_expression
 ```
 
 ## SQL语句模版

diff --git a/docs/zh/openmldb_sql/dql/JOIN_CLAUSE.md b/docs/zh/openmldb_sql/dql/JOIN_CLAUSE.md
@@ -16,16 +16,16 @@ LAST JOIN 是 OpenMLDB SQL 拓展的 JOIN类型. 它的语法和 LEFT JOIN 基
 
 ## Syntax
 
-```
-join:
-    TableRef "LAST" "JOIN" TableRef [OrderByClause] "ON" Expression 
-    | TableRef join_type "JOIN" TableRef "ON" Expression
+```yacc
+join_operation:
+  condition_join_operation
 
-join_type:
-    'LEFT' [OUTER]
+condition_join_operation:
+  from_item LEFT [ OUTER ] JOIN from_item join_condition
+  | from_item LAST JOIN [ ORDER BY ordering_expression ] from_item join_condition
 
-order_by_clause:
-    'ORDER' 'BY' <COLUMN_NAME>
+join_condition:
+  ON bool_expression
 ```
 
 ### 使用限制说明

diff --git a/docs/zh/openmldb_sql/dql/LIMIT_CLAUSE.md b/docs/zh/openmldb_sql/dql/LIMIT_CLAUSE.md
@@ -4,9 +4,9 @@ Limit子句用于限制返回的结果条数。Limit支持接受一个参数，
 
 ## Syntax
 
-```sql
-LimitClause
-         ::= 'LIMIT' int_leteral
+```yacc
+limit_clause:
+  LIMIT numeric_expression
 ```
 
 ## SQL语句模版

diff --git a/docs/zh/openmldb_sql/dql/NO_TABLE_SELECT_CLAUSE.md b/docs/zh/openmldb_sql/dql/NO_TABLE_SELECT_CLAUSE.md
@@ -4,14 +4,8 @@
 
 ## Syntax
 
-```sql
-NoTableSelectClause
-	::= 'SELECT' SelectExprList
-SelectExprList
-         ::= SelectExpr ( ',' SelectExpr )*
-SelectExpr    ::= ( Identifier '.' ( Identifier '.' )? )? '*'
-           | ( Expression | '{' Identifier Expression '}' ) ['AS' Identifier]
-
+```yacc
+SELECT { expression [ [ AS ] alias ] } [, ...];
 ```
 
 ## SQL语句模版

diff --git a/docs/zh/openmldb_sql/dql/SELECT_INTO_STATEMENT.md b/docs/zh/openmldb_sql/dql/SELECT_INTO_STATEMENT.md
@@ -5,21 +5,14 @@
 ```
 ## Syntax
 
-```sql
-SelectIntoStmt
-						::= SelectStmt 'INTO' 'OUTFILE' filePath SelectIntoOptionList
-
-filePath 
-						::= string_literal
-SelectIntoOptionList
-						::= 'OPTIONS' '(' SelectInfoOptionItem (',' SelectInfoOptionItem)* ')'
-
-SelectInfoOptionItem
-						::= 'DELIMITER' '=' string_literal
-						|'HEADER' '=' bool_literal
-						|'NULL_VALUE' '=' string_literal
-						|'FORMAT' '=' string_literal
-						|'MODE' '=' string_literal
+```yacc
+select_into_statement:
+  query INTO OUTFILE string_file_path
+  [ OPTIONS options_list ]
+  [ CONFIG options_list ]
+
+options_list:
+  ( { key = value } [, ...] )
 ```
 
 `SELECT INTO OUTFILE`分为三个部分。

diff --git a/docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md b/docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md
@@ -2,122 +2,102 @@
 
 ## Syntax
 
-### SelectStmt
+### Syntax Notation
 
-```yacc
-SelectStmt
-         ::= WithClause ( NoTableSelectClause | SelectStmtFromTable) 
-
-WithClause
-         ::= 'WITH' non_recursive_cte [, ...]
-
-non_recursive_cte
-         ::= cte_name 'AS' '(' SelectStmt ')'
-
-NoTableSelectClause
-         ::= 'SELECT' SelectExprList      
-
-SelectStmtFromTable
-         ::= SelectStmtBasic 'FROM' TableRefs [WhereClause] [GroupByClause] [HavingClause] [WindowClause] [OrderByClause] [LimitClause]
-           
-JoinClause
-         ::= TableRef JoinType 'JOIN' TableRef [OrderClause] 'ON' Expression 
-JoinType ::= 'LAST'           
-         
-WhereClause
-         ::= 'WHERE' Expression
-         
-GroupByClause
-         ::= 'GROUP' 'BY' ByList
-
-HavingClause
-         ::= 'HAVING' Expression 
-         
-WindowClause
-         ::= ( 'WINDOW' WindowDefinition ( ',' WindowDefinition )* )   
-         
-OrderByClause  ::= 'ORDER' 'BY' ByList   
-
-ByList   ::= ByItem ( ',' ByItem )*
-
-ByItem   ::= Expression Order
-
-Order    ::= ( 'ASC' | 'DESC' )?
-
-WindowClauseOptional
-         ::= ( 'WINDOW' WindowDefinition ( ',' WindowDefinition )* )?
-WindowDefinition
-         ::= WindowName 'AS' WindowSpec
-
-WindowSpec
-         ::= '(' WindowSpecDetails ')'   
-         
-WindowSpecDetails
-         ::= [ExistingWindowName] [WindowUnionClause] WindowPartitionClause WindowOrderByClause WindowFrameClause (WindowAttribute)*
-
-WindowUnionClause
-        :: = ( 'UNION' TableRefs)
-
-WindowPartitionClause
-         ::= ( 'PARTITION' 'BY' ByList ) 
-
-WindowOrderByClause
-        ::= ( 'ORDER' 'BY' ByList )
+- `[ expr ]`: 中括号，可选部分
+- `{}`: 手动分组
+- `a | b`: 逻辑或，表示 `a` 或 `b`
+- `...`: 重复之前的部分, 重复次数 >= 0
+- 大写变量，例如 `WITH`, 表示 SQL 关键词 "WITH"
+- 小写变量, 例如 `query`, 可以拓展成特定语法结构
 
-WindowFrameClause
-        ::= ( WindowFrameUnits WindowFrameBounds [WindowFrameMaxSize] )
+### Select Statement
 
-WindowFrameUnits
-        ::= 'ROWS'
-          | 'ROWS_RANGE'
-
-WindowFrameBounds
-        ::= 'BETWEEN' WindowFrameBound 'AND' WindowFrameBound
-
-WindowFrameBound
-        ::= ( 'UNBOUNDED' | NumLiteral | IntervalLiteral ) ['OPEN'] 'PRECEDING'
-          | 'CURRENT' 'ROW'
-
-WindowAttribute
-        ::= WindowExcludeCurrentTime
-          | WindowExcludeCurrentRow
-          | WindowInstanceNotInWindow
-
-WindowExcludeCurrentTime
-        ::= 'EXCLUDE' 'CURRENT_TIME'
-
-WindowExcludeCurrentRow
-        ::= 'EXCLUDE' 'CURRENT_ROW'
-
-WindowInstanceNotInWindow
-        :: = 'INSTANCE_NOT_IN_WINDOW'
-
-WindowFrameMaxSize
-        :: = 'MAXSIZE' NumLiteral
-```
-
-### SelectExprList
-
-```sql
-SelectExprList
-         ::= SelectExpr ( ',' SelectExpr )*
-SelectExpr    ::= ( Identifier '.' ( Identifier '.' )? )? '*'
-           | ( Expression | '{' Identifier Expression '}' ) ['AS' Identifier]
-
-```
-
-### TableRefs
-
-```sql
-TableRefs
-         ::= EscapedTableRef ( ',' EscapedTableRef )*
-TableRef ::= TableFactor
-           | JoinClause
-TableFactor
-         ::= TableName [TableAsName]
-           | '(' ( ( SelectStmt ) ')' TableAsName | TableRefs ')' )
-TableAsName
-         ::= 'AS'? Identifier
+```yacc
+query_statement:
+  query [ CONFIG ( { key = value }[, ...] )]
+
+query:
+  [ WITH {non_recursive_cte}[, ...] ]
+  { select | ( query ) | set_operation }
+  [ ORDER BY ordering_expression ]
+  [ LIMIT count ]
+
+select:
+  SELECT select_list
+  [ FROM from_item ]
+  [ WHERE bool_expression ]
+  [ GROUP BY group_by_specification ]
+  [ HAVING bool_expression ]
+  [ window_clause ]
+
+set_operation:
+  query set_operator query
+
+non_recursive_cte:
+  cte_name AS ( query )
+
+set_operator:
+  UNION ALL
+
+from_item:
+  table_name [ as_alias ]
+  | { join_operation | ( join_operation ) }
+  | ( query ) [ as_alias ]
+  | cte_name [ as_alias ]
+
+as_alias:
+  [ AS ] alias_name
+
+join_operation:
+  condition_join_operation
+
+condition_join_operation:
+  from_item LEFT [ OUTER ] JOIN from_item join_condition
+  | from_item LAST JOIN [ ORDER BY ordering_expression ] from_item join_condition
+
+join_condition:
+  ON bool_expression
+
+window_clause:
+  WINDOW named_window_expression [, ...]
+
+named_window_expression:
+  named_window AS { named_window | ( window_specification ) }
+
+window_specification:
+  [ UNION ( from_item [, ...] ) ]
+  PARTITION BY expression [ ORDER BY ordering_expression ]
+  window_frame_clause [ window_attr [, ...] ]
+
+window_frame_clause:
+  frame_units BETWEEN frame_bound AND frame_bound [ MAXSIZE numeric_expression ] )
+
+frame_unit:
+  ROWS 
+  | ROWS_RANGE
+
+frame_boud:
+  { UNBOUNDED | numeric_expression | interval_expression } [ OPEN ] PRECEDING
+  | CURRENT ROW
+
+window_attr:
+  EXCLUDE CURRENT_TIME
+  | EXCLUDE CURRENT_ROW
+  | INSTANCE_NOT_IN_WINDOW
+
+// each item in select list is one of:
+// - *
+// - expression.*
+// - expression
+select_list:
+  { select_all | select_expression } [, ...]
+
+select_all:
+  [ expression. ]*
+
+select_expression:
+  expression [ [ AS ] alias ]
 ```
 
 ## SELECT语句元素

diff --git a/docs/zh/openmldb_sql/dql/WHERE_CLAUSE.md b/docs/zh/openmldb_sql/dql/WHERE_CLAUSE.md
@@ -4,10 +4,9 @@ Where 子句用于设置过滤条件，查询结果中只会包含满足条件
 
 ## Syntax
 
-```sql
-WhereClause
-         ::= 'WHERE' Expression
-
+```yacc
+where_clause:
+  WHERE bool_expression
 ```
 
 ## SQL语句模版