From 992de88d2ba73707777bf3b2865df68e3fec8113 Mon Sep 17 00:00:00 2001 From: aceforeverd Date: Sat, 20 Apr 2024 10:02:24 +0800 Subject: [PATCH] docs: call statement and request mode SQL (#3884) --- docs/en/openmldb_sql/dml/CALL_STATEMENT.md | 23 +++ docs/en/openmldb_sql/dml/index.rst | 1 + docs/en/openmldb_sql/dql/SELECT_STATEMENT.md | 195 ++++++++++--------- docs/zh/openmldb_sql/dml/CALL_STATEMENT.md | 23 +++ docs/zh/openmldb_sql/dml/index.rst | 1 + docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md | 26 +++ 6 files changed, 173 insertions(+), 96 deletions(-) create mode 100644 docs/en/openmldb_sql/dml/CALL_STATEMENT.md create mode 100644 docs/zh/openmldb_sql/dml/CALL_STATEMENT.md diff --git a/docs/en/openmldb_sql/dml/CALL_STATEMENT.md b/docs/en/openmldb_sql/dml/CALL_STATEMENT.md new file mode 100644 index 00000000000..37d704746e9 --- /dev/null +++ b/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") +``` diff --git a/docs/en/openmldb_sql/dml/index.rst b/docs/en/openmldb_sql/dml/index.rst index 87dd06d3db1..d791ad68f81 100644 --- a/docs/en/openmldb_sql/dml/index.rst +++ b/docs/en/openmldb_sql/dml/index.rst @@ -10,3 +10,4 @@ Data Manipulation Statement（DML） LOAD_DATA_STATEMENT DELETE_STATEMENT ALTER_STATEMENT + CALL_STATEMENT diff --git a/docs/en/openmldb_sql/dql/SELECT_STATEMENT.md b/docs/en/openmldb_sql/dql/SELECT_STATEMENT.md index 534f71f7280..71e3032a57a 100644 --- a/docs/en/openmldb_sql/dql/SELECT_STATEMENT.md +++ b/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))) +``` + diff --git a/docs/zh/openmldb_sql/dml/CALL_STATEMENT.md b/docs/zh/openmldb_sql/dml/CALL_STATEMENT.md new file mode 100644 index 00000000000..526c6b45757 --- /dev/null +++ b/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") +``` diff --git a/docs/zh/openmldb_sql/dml/index.rst b/docs/zh/openmldb_sql/dml/index.rst index 0f66fe0d2e7..7d56a04d87e 100644 --- a/docs/zh/openmldb_sql/dml/index.rst +++ b/docs/zh/openmldb_sql/dml/index.rst @@ -10,3 +10,4 @@ LOAD_DATA_STATEMENT DELETE_STATEMENT ALTER_STATEMENT + CALL_STATEMENT diff --git a/docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md b/docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md index 215e3917b3a..d26d1c9fd96 100644 --- a/docs/zh/openmldb_sql/dql/SELECT_STATEMENT.md +++ b/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）。