docs: call statement and request mode SQL (#3884)

docs/en/openmldb_sql/dml/CALL_STATEMENT.md

@@ -0,0 +1,23 @@
+# CALL
+
+Invoke a procedure
+
+## Syntax
+
+```yacc
+CALL [db_name.]procedure_name (procedure_argument[, …])
+```
+
+## Use CALL statement to invoke a deployment
+
+SQL [Deployment](../deployment_manage/DEPLOY_STATEMENT.md] is implemented internally with stored procedure, so it's natural to invoke a deployed deployment with CALL statement, required parameters are exactly the same with deployment SQL's request table schema.
+
+## Examples
+
+```sql
+-- table t1 schema is (id int, val string)
+deploy dp1 select * from t1;
+
+-- dp1 has two parameter corresponding to table t1's schema: (int, string)
+call dp1 (12, "str")
+```

docs/en/openmldb_sql/dml/index.rst

@@ -10,3 +10,4 @@ Data Manipulation Statement（DML）
     LOAD_DATA_STATEMENT
     DELETE_STATEMENT
     ALTER_STATEMENT
+    CALL_STATEMENT

docs/en/openmldb_sql/dql/SELECT_STATEMENT.md

@@ -1,124 +1,98 @@
 # SELECT Overview
 
-## Syntax
-
-### SelectStmt
-
-```sql
-SelectStmt
-         ::= WithClause ( NoTableSelectClause | SelectStmtFromTable) 
-
-WithClause
-         ::= 'WITH' non_recursive_cte [, ...]
-
-non_recursive_cte
-         ::= cte_name 'AS' '(' SelectStmt ')'
+## Syntax Notation
 
-NoTableSelectClause
-         ::= 'SELECT' SelectExprList      
+- Square brackets `[ ]`: Optional clause.
+- Curly braces with vertical bars `{ a | b | c }`: Logical OR. Select one option.
+- Ellipsis `...`: Preceding item can repeat.
 
-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 )*
+## Syntax
 
-ByItem   ::= Expression Order
+```yacc
+query_statement:
+  query [ CONFIG ( { key = value }[, ...] )]
 
-Order    ::= ( 'ASC' | 'DESC' )?
+query:
+  [ WITH {non_recursive_cte}[, ...] ]
+  { select | ( query ) | set_operation }
+  [ ORDER BY ordering_expression ]
+  [ LIMIT count ]
 
-WindowClauseOptional
-         ::= ( 'WINDOW' WindowDefinition ( ',' WindowDefinition )* )?
-WindowDefinition
-         ::= WindowName 'AS' WindowSpec
+select:
+  SELECT select_list
+  [ FROM from_item ]
+  [ WHERE bool_expression ]
+  [ GROUP BY group_by_specification ]
+  [ HAVING bool_expression ]
+  [ window_clause ]
 
-WindowSpec
-        ::= '(' WindowSpecDetails ')'   
+set_operation:
+  query set_operator query
 
-WindowSpecDetails
-        ::= [ExistingWindowName] [WindowUnionClause] WindowPartitionClause WindowOrderByClause WindowFrameClause (WindowAttribute)*
+non_recursive_cte:
+  cte_name AS ( query )
 
-WindowUnionClause
-	:: = ( 'UNION' TableRefs)
+set_operator:
+  UNION { ALL | DISTINCT }
 
-WindowPartitionClause
-         ::= ( 'PARTITION' 'BY' ByList ) 
+from_item:
+  table_name [ as_alias ]
+  | { join_operation | ( join_operation ) }
+  | ( query ) [ as_alias ]
+  | cte_name [ as_alias ]
 
-WindowOrderByClause
-        ::= ( 'ORDER' 'BY' ByList )
+as_alias:
+  [ AS ] alias_name
 
-WindowFrameClause
-        ::= ( WindowFrameUnits WindowFrameBounds [WindowFrameMaxSize] )
+join_operation:
+  condition_join_operation
 
-WindowFrameUnits
-        ::= 'ROWS'
-          | 'ROWS_RANGE'
+condition_join_operation:
+  from_item LEFT [ OUTER ] JOIN from_item join_condition
+  | from_item LAST JOIN [ ORDER BY ordering_expression ] from_item join_condition
 
-WindowFrameBounds
-        ::= 'BETWEEN' WindowFrameBound 'AND' WindowFrameBound
+join_condition:
+  ON bool_expression
 
-WindowFrameBound
-        ::= ( 'UNBOUNDED' | NumLiteral | IntervalLiteral ) ['OPEN'] 'PRECEDING'
-          | 'CURRENT' 'ROW'
+window_clause:
+  WINDOW named_window_expression [, ...]
 
-WindowAttribute
-        ::= WindowExcludeCurrentTime
-          | WindowExcludeCurrentRow
-          | WindowInstanceNotInWindow
+named_window_expression:
+  named_window AS { named_window | ( window_specification ) }
 
-WindowExcludeCurrentTime
-        ::= 'EXCLUDE' 'CURRENT_TIME'
+window_specification:
+  [ UNION ( from_item [, ...] ) ]
+  PARTITION BY expression [ ORDER BY ordering_expression ]
+  window_frame_clause [ window_attr [, ...] ]
 
-WindowExcludeCurrentRow
-        ::= 'EXCLUDE' 'CURRENT_ROW'
+window_frame_clause:
+  frame_units BETWEEN frame_bound AND frame_bound [ MAXSIZE numeric_expression ] )
 
-WindowInstanceNotInWindow
-        :: = 'INSTANCE_NOT_IN_WINDOW'
+frame_unit:
+  ROWS 
+  | ROWS_RANGE
 
-WindowFrameMaxSize
-        :: = 'MAXSIZE' NumLiteral
-```
+frame_boud:
+  { UNBOUNDED | numeric_expression | interval_expression } [ OPEN ] PRECEDING
+  | CURRENT ROW
 
-### SelectExprList
+window_attr:
+  EXCLUDE CURRENT_TIME
+  | EXCLUDE CURRENT_ROW
+  | INSTANCE_NOT_IN_WINDOW
 
-```
-SelectExprList
-         ::= SelectExpr ( ',' SelectExpr )*
-SelectExpr    ::= ( Identifier '.' ( Identifier '.' )? )? '*'
-           | ( Expression | '{' Identifier Expression '}' ) ['AS' Identifier]
-           
-           
-```
+// each item in select list is one of:
+// - *
+// - expression.*
+// - expression
+select_list:
+  { select_all | select_expression } [, ...]
 
-### TableRefs
+select_all:
+  [ expression. ]*
 
-```
-TableRefs
-         ::= EscapedTableRef ( ',' EscapedTableRef )*
-TableRef ::= TableFactor
-           | JoinClause
-TableFactor
-         ::= TableName [TableAsName]
-           | '(' ( ( SelectStmt ) ')' TableAsName | TableRefs ')' )
-TableAsName
-         ::= 'AS'? Identifier
+select_expression:
+  expression [ [ AS ] alias ]
 ```
 
 ## SELECT Statement
@@ -142,3 +116,32 @@ The largest number of bytes to scan is limited, namely `scan_max_bytes_size`, de
 
 Even if the `scan_max_bytes_size` is set to unlimited, the `SELECT` statement may failed, e.g. client errors `body_size=xxx from xx:xxxx is too large`, ` Fail to parse response from xx:xxxx by baidu_std at client-side`. We don't recommend to use `SELECT` in online mode or the stand-alone version. If you want to get the count of the online table, please use `SELECT COUNT(*) FROM table_name;`.
 ```
+
+## CONFIG clause
+
+`query_statement` is able to take optional CONFIG clause, as `CONFIG ( key_string = value_expr, ...)`, which make extra configuration over current query. Supported keys and values are:
+
+| key_string | value_expr type | Note |
+| ---------- | ---------  | ---- |
+| execute_mode | string | SQL `execute_mode`, choose one: `online`, `request`, `offline`. default to value of system variable `execute_mode`. You can view it via SQL `show variables` |
+| values | Any valid expression | See [SQL request query in RAW SQL](#sql-request-query-in-raw-sql) |
+
+## SQL request query in raw SQL
+
+OpenMLDB >= 0.9.0 make it possible for a query statement to run as request mode without extra request row info passed in , for example from one of the parameter in JAVA SDK. Those request row informations are
+instead allowed inside CONFIG clause, as `execute_mode` and `values`. When CONFIG `execute_mode = 'request'`，it firstly parse request row value in CONFIG `values`.
+CONFIG `values` supports two formats：
+1. Parentheses `()` surrounded expression list, representing single request row. For example `(1, "str", timestamp(1000) )` 
+2. Square brackets `[]` surrounded parentheses expression lists, say it is surrounding N parentheses expressions, representing N request rows. For example `[ (1, "str", timestamp(1000)), (2, "foo", timestamp(5000)) ]`
+
+Parentheses `()` expression is the minimal unit to a request row, every expression inside parentheses should match exactly to the data type of request table schema, which current SQL contains.
+
+```sql
+-- table t1 of schema ( id int, val string, ts timestamp )
+
+-- executing SQL as request mode, with request row (10, "foo", timestamp(4000))
+SELECT id, count (val) over (partition by id order by ts rows between 10 preceding and current row)
+FROM t1
+CONFIG (execute_mode = 'online', values = (10, "foo", timestamp (4000)))
+```
+

docs/zh/openmldb_sql/dml/CALL_STATEMENT.md

@@ -0,0 +1,23 @@
+# CALL
+
+调用一个存储过程
+
+## 语法
+
+```yacc
+CALL [db_name.]procedure_name (procedure_argument[, …])
+```
+
+## CALL 语句调用 Deployment
+
+SQL [Deployment](../deployment_manage/DEPLOY_STATEMENT.md) 内部以存储过程的形式实现，它的参数是 SQL 主表的 schema, 可以通过 CALL 语句在 SQL 上直接执行验证对应的 deployment.
+
+## Examples
+
+```sql
+-- table t1 schema is (id int, val string)
+deploy dp1 select * from t1;
+
+-- 调用存储过程 dp1, dp1 有两个参数 (int, string)
+call dp1 (12, "str")
+```

docs/zh/openmldb_sql/dml/index.rst

@@ -10,3 +10,4 @@
     LOAD_DATA_STATEMENT
     DELETE_STATEMENT
     ALTER_STATEMENT
+    CALL_STATEMENT

docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md

@@ -130,6 +130,32 @@ FROM 子句的来源可以是:
 - JOIN 操作, OpenMLDB 支持 LEFT JOIN 和 LAST JOIN
 - 任意子查询, 被括在括号中
 
+## CONFIG 子句
+
+`query_statement` 最后可以带可选的 CONFIG 子句，`CONFIG ( key_string = value_expr, ...)` 的形式，表示对当前 SQL 的额外配置信息，目前支持的选项有：
+
+| key_string | value_expr 类型 | 说明 |
+| ---------- | ---------  | ---- |
+| execute_mode | string | 表示当前 SQL 的执行模式，可选值有 `online`, `request`, `offline`, 如果不填，默认值为系统变量 `execute_mode` 设置的值，可以通过 SQL `show variables` 查看。 |
+| values | 任意合法的表达式 | 详见 [纯 SQL 在线请求模式查询](#sql-request-query-in-raw-sql) |
+
+## SQL request query in raw SQL
+
+OpenMLDB >= 0.9.0 支持在 query statement 中用 CONFIG 子句配置 SQL 的执行模式 (`execute_mode`) 和请求行信息(`values`). 即当 CONFIG `execute_mode = 'request'` 时，将首先读取 CONFIG 中 `values` 的值, 并解析成请求行，因此不需要在其他地方，例如 JAVA SDK 接口手动传入请求行。CONFIG `values` 支持的格式有两种：
+1. 小括号 `()` 包括起来的表达式列表，表示一行数据。例如 `(1, "str", timestamp(1000) )` 
+2. 中括号 `[]` 包括起来的 N 个小括号 `()` 列表， 表示 N 行数据。例如 `[ (1, "str", timestamp(1000)), (2, "foo", timestamp(5000)) ]`
+
+小括号 `()` 包含的整个表达式表示单行请求行，它内部的每一个表达式类型必须和 SQL 请求表的 schema 严格一致。 第一种格式，表示单行的在线请求模式查询，查询结果为单行数据。第二中格式，表示 N 行的在线请求模式查询，查询结果为 N 行。
+
+```sql
+-- table t1 of schema ( id int, val string, ts timestamp )
+
+-- 执行请求行为 (10, "foo", timestamp(4000)) 的在线请求模式 query
+SELECT id, count (val) over (partition by id order by ts rows between 10 preceding and current row)
+FROM t1
+CONFIG (execute_mode = 'online', values = (10, "foo", timestamp (4000)))
+```
+
 ## 离线同步模式 Query
 
 设置`SET @@sync_job=true`后的 Query 语句，就是离线同步模式下的 Query。在这个状态下的 Query 会展示结果到CLI（不建议在SDK中使用这种模式，不会得到正常的ResultSet）。