[NO ISSUE][DOC] SQL++ EBNF doc cleanup
- user model changes: no
- storage format changes: no
- interface changes: no
Details:
- Cleanup and add missing elements to SQL++ EBNF doc
Change-Id: Id54a67dc0d3747a0e3043378f992eb3e3497cbce
Reviewed-on: https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/9727
Integration-Tests: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Tested-by: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Reviewed-by: Dmitry Lychagin <dmitry.lychagin@couchbase.com>
Reviewed-by: Ali Alsuliman <ali.al.solaiman@gmail.com>
diff --git a/asterixdb/asterix-doc/src/main/grammar/sqlpp.ebnf b/asterixdb/asterix-doc/src/main/grammar/sqlpp.ebnf
index 45d7d6e..d338068 100644
--- a/asterixdb/asterix-doc/src/main/grammar/sqlpp.ebnf
+++ b/asterixdb/asterix-doc/src/main/grammar/sqlpp.ebnf
@@ -5,8 +5,7 @@
| OperatorExpr Operator OperatorExpr?
| OperatorExpr "BETWEEN" OperatorExpr "AND" OperatorExpr
-QuantifiedExpr::= ( "SOME" | "EVERY" ) Variable "IN" Expr ( "," Variable "in" Expr )*
- "SATISFIES" Expr ("END")?
+QuantifiedExpr::= ( "SOME" | "EVERY" ) Variable "IN" Expr ( "," Variable "IN" Expr )* "SATISFIES" Expr ("END")?
PathExpr ::= PrimaryExpr ("." Identifier | "[" Expr (":" (Expr)? )? "]")*
@@ -35,13 +34,13 @@
OrdinaryFunctionCall ::= Identifier "(" Expr ("," Expr)* ")"
-AggregateFunctionCall ::= Identifier "(" ("DISTINCT")? Expr ")"
+AggregateFunctionCall ::= Identifier "(" ("DISTINCT")? Expr ")" ("FILTER" "(" "WHERE" Expr ")")?
CaseExpr ::= SimpleCaseExpr | SearchedCaseExpr
SimpleCaseExpr ::= "CASE" Expr ("WHEN" Expr "THEN" Expr)+ ("ELSE" Expr)? "END"
-SearchedCaseExpr ::= "CASE"("WHEN" Expr "THEN" Expr)+ ("ELSE" Expr)? "END"
+SearchedCaseExpr ::= "CASE" ("WHEN" Expr "THEN" Expr)+ ("ELSE" Expr)? "END"
Constructor ::= ObjectConstructor | ArrayConstructor | MultisetConstructor
@@ -53,24 +52,26 @@
Query ::= (Expr | Selection) ";"
-Selection ::= WithClause? QueryBlock UnionOption* OrderByClause? LimitClause?
+Selection ::= WithClause? QueryBlock UnionOption* OrderByClause? ( LimitClause | OffsetClause )?
-QueryBlock ::= SelectClause StreamGenerator?
- |StreamGenerator SelectClause
+QueryBlock ::= SelectClause StreamGenerator?
+ | StreamGenerator SelectClause
StreamGenerator::= FromClause LetClause? WhereClause? (GroupByClause LetClause? HavingClause?)?
-SelectClause ::= "SELECT" ("DISTINCT" | "ALL")? "VALUE" Expr
- | "SELECT" ("DISTINCT" | "ALL")? ((Expr ("AS"? Identifier)?) | "*" | Identifier "." "*") ("," ((Expr ("AS"? Identifier)?) | "*" | Identifier "." "*"))*
+SelectClause ::= "SELECT" ("DISTINCT" | "ALL")? ( "VALUE" Expr | Projection ("," Projection)*)
+
+Projection ::= (Expr ("AS"? Identifier)?) | (VariableRef "." "*") | "*"
FromClause ::= "FROM" FromTerm ("," FromTerm)*
-FromTerm ::= NamedExpr JoinStep*
+FromTerm ::= NamedExpr (JoinStep | UnnestStep)*
-NamedExpr ::= Expr
- |Expr "AS"? Variable
+NamedExpr ::= Expr ("AS"? Variable)?
-JoinStep ::= ("INNER" | ("LEFT" "OUTER"?))? ("JOIN" NamedExpr "ON" Expr | "UNNEST" NamedExpr)
+JoinStep ::= ("INNER" | ( ( "LEFT" | "RIGHT" ) "OUTER"?))? "JOIN" NamedExpr "ON" Expr
+
+UnnestStep ::= ("INNER" | ( "LEFT" "OUTER"?))? "UNNEST" NamedExpr
LetClause ::= "LET" Variable "=" Expr ("," Variable "=" Expr)*
@@ -86,9 +87,9 @@
OrdinaryGroupingSet ::= GroupByExprPair | ( "(" GroupByExprPair ( "," GroupByExprPair )* ")")
-GroupByExprPair ::= Expr ("AS"? Identifier)?
+GroupByExprPair ::= Expr ("AS"? Variable)?
-GroupAsClause ::= "GROUP AS" Identifier
+GroupAsClause ::= "GROUP AS" Variable
HavingClause ::= "HAVING" Expr
@@ -96,11 +97,9 @@
UnionOption ::= "UNION ALL" (QueryBlock | Subquery)
-WithClause ::= "WITH" Identifier "AS" Expr
- ("," Identifier "AS" Expr)*
+WithClause ::= "WITH" Variable "AS" Expr ("," Variable "AS" Expr)*
-OrderbyClause ::= "ORDER BY" Expr ( "ASC" | "DESC" )?
- ( "," Expr ( "ASC" | "DESC" )? )*
+OrderbyClause ::= "ORDER BY" Expr ( "ASC" | "DESC" )? ( "," Expr ( "ASC" | "DESC" )? )*
LimitClause ::= "LIMIT" Expr OffsetClause?
@@ -110,8 +109,7 @@
WindowFunctionCall ::= WindowFunctionType "(" WindowFunctionArguments ")" WindowFunctionOptions? "OVER" (Variable "AS")? "(" WindowDefinition")"
-WindowFunctionType ::= AggregateFunction
- | WindowFunction
+WindowFunctionType ::= AggregateFunction | WindowFunction
WindowFunctionArguments ::= ( ("DISTINCT")? Expr | (Expr ("," Expr ("," Expr)? )? )? )
@@ -126,11 +124,10 @@
WindowFrameClause ::= ("ROWS" | "RANGE" | "GROUPS") WindowFrameExtent
WindowFrameExtent ::= ( ( "UNBOUNDED" | Expr ) "PRECEDING" | "CURRENT" "ROW" ) |
-"BETWEEN"( "UNBOUNDED" "PRECEDING" | "CURRENT" "ROW" | Expr ( "PRECEDING" | "FOLLOWING" ) )
-"AND" ( "UNBOUNDED" "FOLLOWING" | "CURRENT" "ROW" | Expr ( "PRECEDING" | "FOLLOWING" ) )
+ "BETWEEN" ( "UNBOUNDED" "PRECEDING" | "CURRENT" "ROW" | Expr ( "PRECEDING" | "FOLLOWING" ) )
+ "AND" ( "UNBOUNDED" "FOLLOWING" | "CURRENT" "ROW" | Expr ( "PRECEDING" | "FOLLOWING" ) )
-WindowFrameExclusion ::= "EXCLUDE" ( "CURRENT" "ROW" | "GROUP" | "TIES" |
-"NO" "OTHERS" )
+WindowFrameExclusion ::= "EXCLUDE" ( "CURRENT" "ROW" | "GROUP" | "TIES" | "NO" "OTHERS" )
Stmnt::= (SingleStmnt ";")+ "EOF"
@@ -147,10 +144,6 @@
UseStmnt ::= "USE" Identifier
-FunctionDeclaration ::= "DELCARE" "FUNCTION" Identifier ParameterList "{" Expr "}"
-
-ParameterList ::= "(" ("VARIABLE" ("," "VARIABLE")*)?")"
-
CreateStmnt ::= CreateDataverse
| CreateType
| CreateDataset
@@ -232,10 +225,12 @@
CreateSynonym ::= "CREATE" "SYNONYM" QualifiedName "FOR" QualifiedName ("IF" "NOT" "EXISTS")?
-CreateFunction ::= "CREATE" ("OR" "REPLACE")? "FUNCTION" QualifiedName ("IF" "NOT" "EXISTS")? FunctionParameters
- ( ("{" Expr "}") | ExternalFunctionDef)
+FunctionDeclaration ::= "DECLARE" "FUNCTION" Identifier "(" ( (Variable ("," Variable)*) | "..." )? ")" "{" Expr "}"
-FunctionParameters ::= "(" ("VARIABLE" (":" TypeExpr)? ("," "VARIABLE" (":" TypeExpr)? )* )? ")"
+CreateFunction ::= "CREATE" ("OR" "REPLACE")? "FUNCTION" QualifiedName ("IF" "NOT" "EXISTS")? "(" FunctionParameters? ")"
+ ( ("{" Expr "}") | ExternalFunctionDef )
+
+FunctionParameters ::= ( Variable ((":")? TypeExpr)? ("," Variable ((":")? TypeExpr)? )* ) | "..."
ExternalFunctionDef ::= ("RETURNS" TypeExpr)? "AS" StringLiteral ("," StringLiteral )* "AT" QualifiedName ("WITH" ObjectConstructor)?
@@ -244,7 +239,7 @@
| "INDEX" DoubleQualifiedName
| "FUNCTION" FunctionSignature ) ("IF" "EXISTS")?
-FunctionSignature ::= QualifiedName ( FunctionParameters | ( "(" IntegerLiteral ")" ) | ("@" IntegerLiteral) )
+FunctionSignature ::= QualifiedName ( ( "(" ( FunctionParameters? | IntegerLiteral ) ")" ) | ("@" IntegerLiteral) )
LoadStmnt ::= "LOAD" "DATASET" QualifiedName "USING" AdapterName Configuration ("PRE-SORTED")?
@@ -255,11 +250,3 @@
DeleteStmnt ::= "DELETE" "FROM" QualifiedName (("AS")? Variable)? ("WHERE" Expr)?
SetStmnt ::= "SET" Identifier StringLiteral
-
-
-
-
-
-
-
-
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md
index 9979570..ae203bf 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md
@@ -400,6 +400,8 @@
Note that Window functions, and aggregate functions used as window functions, have a more complex syntax.
Window function calls are described in the section on [Window Queries](#Over_clauses).
+Also note that FILTER expressions can only be specified when calling [Aggregation Pseudo-Functions](#Aggregation_PseudoFunctions).
+
The following example is a function call expression whose value is 8.
##### Example
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md
index 8076140..43445ed 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md
@@ -23,6 +23,8 @@
### SelectClause
****
+### Projection
+****
##### Synonyms for `VALUE`: `ELEMENT`, `RAW`
---
@@ -322,6 +324,8 @@
### JoinStep
****
+### UnnestStep
+****
##### Synonyms for `UNNEST`: `CORRELATE`, `FLATTEN`
---
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/7_ddl_dml.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/7_ddl_dml.md
index 8ed266f..6bfac3b 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/7_ddl_dml.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/7_ddl_dml.md
@@ -51,9 +51,6 @@
### FunctionDeclaration
****
-### ParameterList
-****
-
---
The following is a simple example of a temporary function definition and its use.
@@ -513,6 +510,15 @@
WHERE u.id = userId)[0]
};
+The following is an example of CREATE FUNCTION statement that introduces a function with a variable number of arguments.
+The arguments are accessible in the function body via `args` array parameter.
+
+##### Example
+
+ CREATE FUNCTION strJoin(...) {
+ string_join(args, ",")
+ };
+
External functions can also be loaded into Libraries via the [UDF API](../udf.html). Given
an already loaded library `pylib`, a function `sentiment` mapping to a Python method `sent_model.sentiment` in `sentiment_mod`
would be as follows