examples and small updates for the AQL reference doc
diff --git a/asterix-doc/src/site/markdown/AsterixQueryLanguageReference.md b/asterix-doc/src/site/markdown/AsterixQueryLanguageReference.md
index c9ed3e2..1ed876e 100644
--- a/asterix-doc/src/site/markdown/AsterixQueryLanguageReference.md
+++ b/asterix-doc/src/site/markdown/AsterixQueryLanguageReference.md
@@ -3,38 +3,79 @@
This document provides an overview of the Asterix Query language.
+
## 2. Expressions
Expression ::= ( OperatorExpr | IfThenElse | FLWOGR | QuantifiedExpression )
+
### Primary Expressions
- PrimaryExpr ::= Literal | VariableRef | ParenthesizedExpression | FunctionCallExpr
- | DatasetAccessExpression | ListConstructor | RecordConstructor
+ PrimaryExpr ::= Literal
+ | VariableRef
+ | ParenthesizedExpression
+ | FunctionCallExpr
+ | DatasetAccessExpression
+ | ListConstructor
+ | RecordConstructor
+
#### Literals
- Literal ::= StringLiteral | <INTEGER_LITERAL> | <FLOAT_LITERAL> | <DOUBLE_LITERAL> | <NULL> | <TRUE> | <FALSE>
+ Literal ::= StringLiteral
+ | <INTEGER_LITERAL>
+ | <FLOAT_LITERAL>
+ | <DOUBLE_LITERAL>
+ | "null"
+ | "true"
+ | "false"
StringLiteral ::= <STRING_LITERAL>
+##### Examples
+
+ "a string"
+ 42
+
+
#### Variable References
VariableRef ::= <VARIABLE>
+
+##### Example
+
+ $id
+
#### Parenthesized Expressions
- ParenthesizedExpression ::= <LEFTPAREN> Expression <RIGHTPAREN>
+ ParenthesizedExpression ::= "(" Expression ")"
+
+##### Example
+
+ ( 1 + 1 )
+
#### Function Calls
- FunctionCallExpr ::= FunctionOrTypeName <LEFTPAREN> ( Expression ( "," Expression )* )? <RIGHTPAREN>
-
+ FunctionCallExpr ::= FunctionOrTypeName "(" ( Expression ( "," Expression )* )? ")"
+
+##### Example
+
+ string-length("a string")
+
+
#### Dataset Access
- DatasetAccessExpression ::= <DATASET> ( ( Identifier ( "." Identifier )? )
- | ( <LEFTPAREN> Expression ( "," Expression )* <RIGHTPAREN> ) )
+ DatasetAccessExpression ::= "dataset" ( ( Identifier ( "." Identifier )? )
+ | ( "(" Expression ")" ) )
Identifier ::= <IDENTIFIER> | StringLiteral
+##### Examples
+
+ dataset customers
+ dataset (string-join("customers", $country))
+
+
#### Constructors
ListConstructor ::= ( OrderedListConstructor | UnorderedListConstructor )
@@ -43,20 +84,51 @@
RecordConstructor ::= "{" ( FieldBinding ( "," FieldBinding )* )? "}"
FieldBinding ::= Expression ":" Expression
+##### Examples
+
+ [ "a", "b", "c" ]
+
+ {{ 42, "forty-two", "AsterixDB!" }}
+
+ {
+ "project name" : "AsterixDB"
+ "project members" : {{ "vinayakb", "dtabass", "chenli" }}
+ }
+
+
### Path Expressions
ValueExpr ::= PrimaryExpr ( Field | Index )*
Field ::= "." Identifier
Index ::= "[" ( Expression | "?" ) "]"
+##### Examples
+
+ { "list" : [ "a", "b", "c"] }.list
+
+ [ "a", "b", "c"][2]
+
+ { "list" : [ "a", "b", "c"] }.list[2]
+
+
### Logical Expressions
OperatorExpr ::= AndExpr ( "or" AndExpr )*
AndExpr ::= RelExpr ( "and" RelExpr )*
+##### Example
+
+ $a > 3 and $a < 5
+
+
### Comparison Expressions
RelExpr ::= AddExpr ( ( "<" | ">" | "<=" | ">=" | "=" | "!=" | "~=" ) AddExpr )?
+
+##### Example
+
+ 5 > 3
+
### Arithmetic Expressions
@@ -64,6 +136,11 @@
MultExpr ::= UnaryExpr ( ( "*" | "/" | "%" | <CARET> | "idiv" ) UnaryExpr )*
UnaryExpr ::= ( ( "+" | "-" ) )? ValueExpr
+##### Example
+
+ 3 ^ 2 + 4 ^ 2
+
+
### FLWOGR Expression
FLWOGR ::= ( ForClause | LetClause ) ( Clause )* "return" Expression
@@ -81,16 +158,99 @@
Variable ::= <VARIABLE>
+##### Example
+
+ for $user in dataset FacebookUsers
+ where $user.id = 8
+ return $user
+
+##### Example
+
+ for $user in dataset FacebookUsers
+ for $message in dataset FacebookMessages
+ where $message.author-id = $user.id
+ return
+ {
+ "uname": $user.name,
+ "message": $message.message
+ };
+
+##### Example
+
+ for $user in dataset FacebookUsers
+ let $messages :=
+ for $message in dataset FacebookMessages
+ where $message.author-id = $user.id
+ return $message.message
+ return
+ {
+ "uname": $user.name,
+ "messages": $messages
+ };
+
+##### Example
+
+ for $user in dataset TwitterUsers
+ order by $user.followers_count desc, $user.lang asc
+ return $user
+
+* null is smaller than any other value
+
+##### Example
+
+ for $x in dataset FacebookMessages
+ let $messages := $x.message
+ group by $loc := $x.sender-location with $messages
+ return
+ {
+ "location" : $loc,
+ "message" : $messages
+ }
+
+* after group by only variables that are either in the group-by-list or in the with-list are in scope
+* the variables in the with-clause contain a collection of items after the group by clause (all the values that the variable was bound to in the tuples that make up the group)
+* null is handled as a single value for grouping
+
+##### Example
+
+ for $user in dataset TwitterUsers
+ order by $user.followers_count desc
+ limit 2
+ return $user
+
+##### Example (currently not working)
+
+ for $x in dataset FacebookMessages
+ distinct by $x.sender-location
+ return
+ {
+ "location" : $x.sender-location,
+ "message" : $x.message
+ }
+
+* every variable that is in-scope before the distinct clause is also in scope after the distinct clause
+* works a lot like group by, but for every variable that contains more than one value after the distinct-by clause, one value is picked non-deterministically
+* if the variable is in the disctict-by list, then value is deterministic
+* null is a single value
+
### Conditional Expression
- IfThenElse ::= "if" <LEFTPAREN> Expression <RIGHTPAREN> "then" Expression "else" Expression
+ IfThenElse ::= "if" "(" Expression ")" "then" Expression "else" Expression
+
+##### Example
+
+ if (2 < 3) then "yes" else "no"
### Quantified Expressions
QuantifiedExpression ::= ( ( "some" ) | ( "every" ) ) Variable "in" Expression
( "," Variable "in" Expression )* "satisfies" Expression
+
+##### Examples
+ every $x in [ 1, 2, 3] satisfies $x < 3
+ some $x in [ 1, 2, 3] satisfies $x < 3
## 3. Statements
@@ -103,7 +263,6 @@
| SetStatement
| InsertStatement
| DeleteStatement
- | FeedStatement
| Query
### Declarations
@@ -111,21 +270,48 @@
DataverseDeclaration ::= "use" "dataverse" Identifier
SetStatement ::= "set" Identifier StringLiteral
FunctionDeclaration ::= "declare" "function" Identifier ParameterList "{" Expression "}"
- ParameterList ::= <LEFTPAREN> ( <VARIABLE> ( "," <VARIABLE> )* )? <RIGHTPAREN>
+ ParameterList ::= "(" ( <VARIABLE> ( "," <VARIABLE> )* )? ")"
+
+##### Example
+
+ use dataverse TinySocial;
+
+##### Example
+
+ set simfunction "jaccard";
+ set simthreshold "0.6f";
+
+##### Example
+
+ set simfunction "jaccard";
+ set simthreshold "0.6f";
+
+##### Example
+
+ declare function add($a, $b) {
+ $a + $b
+ };
### Lifecycle Management Statements
- CreateStatement ::= "create" ( TypeSpecification | DatasetSpecification | IndexSpecification | DataverseSpecification | FunctionSpecification )
+ CreateStatement ::= "create" ( DataverseSpecification
+ | TypeSpecification
+ | DatasetSpecification
+ | IndexSpecification
+ | FunctionSpecification )
- DropStatement ::= "drop" ( <DATASET> QualifiedName IfExists
- | "index" DoubleQualifiedName IfExists
- | "type" FunctionOrTypeName IfExists
- | "dataverse" Identifier IfExists
- | "function" FunctionSignature IfExists )
- IfExists ::= ( "if" "exists" )?
QualifiedName ::= Identifier ( "." Identifier )?
DoubleQualifiedName ::= Identifier "." Identifier ( "." Identifier )?
+#### Dataverses
+
+ DataverseSpecification ::= "dataverse" Identifier IfNotExists ( "with format" StringLiteral )?
+
+
+##### Example
+
+ create dataverse TinySocial;
+
#### Types
TypeSpecification ::= "type" FunctionOrTypeName IfNotExists "as" TypeExpr
@@ -137,55 +323,140 @@
TypeReference ::= Identifier
OrderedListTypeDef ::= "[" ( TypeExpr ) "]"
UnorderedListTypeDef ::= "{{" ( TypeExpr ) "}}"
-
+
+##### Example
+
+ create type FacebookUserType as closed {
+ id: int32,
+ alias: string,
+ name: string,
+ user-since: datetime,
+ friend-ids: {{ int32 }},
+ employment: [EmploymentType]
+ }
+
+
#### Datasets
- DatasetSpecification ::= "external" <DATASET> QualifiedName <LEFTPAREN> Identifier <RIGHTPAREN> IfNotExists
- "using" AdapterName Configuration ( "hints" Properties )?
- | "feed" <DATASET> QualifiedName <LEFTPAREN> Identifier <RIGHTPAREN> IfNotExists
- "using" AdapterName Configuration ( ApplyFunction )? PrimaryKey ( "on" Identifier )? ( "hints" Properties )?
- | "internal"? <DATASET> QualifiedName <LEFTPAREN> Identifier <RIGHTPAREN> IfNotExists
- PrimaryKey ( "on" Identifier )? ( "hints" Properties )?
+ DatasetSpecification ::= "internal"? "dataset" QualifiedName "(" Identifier ")" IfNotExists
+ PrimaryKey ( "on" Identifier )? ( "hints" Properties )?
+ | "external" "dataset" QualifiedName "(" Identifier ")" IfNotExists
+ "using" AdapterName Configuration ( "hints" Properties )?
AdapterName ::= Identifier
- Configuration ::= <LEFTPAREN> ( KeyValuePair ( "," KeyValuePair )* )? <RIGHTPAREN>
- KeyValuePair ::= <LEFTPAREN> StringLiteral "=" StringLiteral <RIGHTPAREN>
- Properties ::= ( <LEFTPAREN> Property ( "," Property )* <RIGHTPAREN> )?
+ Configuration ::= "(" ( KeyValuePair ( "," KeyValuePair )* )? ")"
+ KeyValuePair ::= "(" StringLiteral "=" StringLiteral ")"
+ Properties ::= ( "(" Property ( "," Property )* ")" )?
Property ::= Identifier "=" ( StringLiteral | <INTEGER_LITERAL> )
ApplyFunction ::= "apply" "function" FunctionSignature
FunctionSignature ::= FunctionOrTypeName "@" <INTEGER_LITERAL>
PrimaryKey ::= "primary" "key" Identifier ( "," Identifier )*
+
+##### Example
+ create internal dataset FacebookUsers(FacebookUserType) primary key id;
+
+##### Example
+
+ create external dataset Lineitem(LineitemType) using localfs (
+ ("path"="127.0.0.1://SOURCE_PATH"),
+ ("format"="delimited-text"),
+ ("delimiter"="|"));
+
#### Indices
- IndexSpecification ::= "index" Identifier IfNotExists "on" QualifiedName <LEFTPAREN> ( Identifier ) ( "," Identifier )* <RIGHTPAREN> ( "type" IndexType )?
- IndexType ::= "btree" | "rtree" | "keyword" | "fuzzy keyword" | "ngram" <LEFTPAREN> <INTEGER_LITERAL> <RIGHTPAREN> | "fuzzy ngram" <LEFTPAREN> <INTEGER_LITERAL> <RIGHTPAREN>
+ IndexSpecification ::= "index" Identifier IfNotExists "on" QualifiedName
+ "(" ( Identifier ) ( "," Identifier )* ")" ( "type" IndexType )?
+ IndexType ::= "btree"
+ | "rtree"
+ | "keyword"
+ | "fuzzy keyword"
+ | "ngram" "(" <INTEGER_LITERAL> ")"
+ | "fuzzy ngram" "(" <INTEGER_LITERAL> ")"
-#### Dataverses
+##### Example
- DataverseSpecification ::= "dataverse" Identifier IfNotExists ( "with format" StringLiteral )?
+ create index fbAuthorIdx on FacebookMessages(author-id) type btree;
+
+##### Example
+
+ create index fbSenderLocIndex on FacebookMessages(sender-location) type rtree;
+
+##### Example
+
+ create index fbMessageIdx on FacebookMessages(message) type keyword;
+
#### Functions
- FunctionSpecification ::= "function" FunctionOrTypeName IfNotExists ParameterList "{" Expression "}"
+ FunctionSpecification ::= "function" FunctionOrTypeName IfNotExists ParameterList "{" Expression "}"
+
+##### Example
+
+ create function add($a, $b) {
+ $a + $b
+ };
+
+
+#### Removal
+
+ DropStatement ::= "drop" ( "dataverse" Identifier IfExists
+ | "type" FunctionOrTypeName IfExists
+ | "dataset" QualifiedName IfExists
+ | "index" DoubleQualifiedName IfExists
+ | "function" FunctionSignature IfExists )
+ IfExists ::= ( "if" "exists" )?
+
+##### Example
+
+ drop dataset FacebookUsers if exists;
+
+##### Example
+
+ drop index fbSenderLocIndex;
+
+##### Example
+
+ drop type FacebookUserType;
+
+##### Example
+
+ drop dataverse TinySocial;
+
+##### Example
+
+ drop function add;
+
### Import/Export Statements
- LoadStatement ::= "load" <DATASET> QualifiedName "using" AdapterName Configuration ( "pre-sorted" )?
+ LoadStatement ::= "load" "dataset" QualifiedName "using" AdapterName Configuration ( "pre-sorted" )?
+
+##### Example
+
+ load dataset FacebookUsers using localfs
+ (("path"="localhost:///Users/zuck/AsterixDB/load/fbu.adm"),("format"="adm"));
+
### Modification Statements
- InsertStatement ::= "insert" "into" <DATASET> QualifiedName Query
- DeleteStatement ::= "delete" Variable "from" <DATASET> QualifiedName ( "where" Expression )?
+ InsertStatement ::= "insert" "into" "dataset" QualifiedName Query
+ DeleteStatement ::= "delete" Variable "from" "dataset" QualifiedName ( "where" Expression )?
+
+##### Example
-### Feed Management Statements
+ insert into dataset UsersCopy (for $user in dataset FacebookUsers return $user)
- FeedStatement ::= "begin" "feed" QualifiedName
- | "suspend" "feed" QualifiedName
- | "resume" "feed" QualifiedName
- | "end" "feed" QualifiedName
- | "alter" "feed" QualifiedName "set" Configuration
+##### Example
+
+ delete $user from dataset FacebookUsers where $user.id = 8;
+
### Queries
Query ::= Expression
+##### Example
+
+ for $praise in {{ "great", "brilliant", "awesome" }}
+ return
+ string-concat(["AsterixDB is ", $praise])