http://git-wip-us.apache.org/repos/asf/asterixdb-site/blob/100cb803/content/docs/0.9.1/aql/manual.html
----------------------------------------------------------------------
diff --git a/content/docs/0.9.1/aql/manual.html
b/content/docs/0.9.1/aql/manual.html
new file mode 100644
index 0000000..4b7f477
--- /dev/null
+++ b/content/docs/0.9.1/aql/manual.html
@@ -0,0 +1,1096 @@
+<!DOCTYPE html>
+<!--
+ | Generated by Apache Maven Doxia at 2017-04-24
+ | Rendered using Apache Maven Fluido Skin 1.3.0
+-->
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta name="Date-Revision-yyyymmdd" content="20170424" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>AsterixDB – The Asterix Query Language, Version 1.0</title>
+ <link rel="stylesheet" href="../css/apache-maven-fluido-1.3.0.min.css" />
+ <link rel="stylesheet" href="../css/site.css" />
+ <link rel="stylesheet" href="../css/print.css" media="print" />
+
+
+ <script type="text/javascript"
src="../js/apache-maven-fluido-1.3.0.min.js"></script>
+
+
+
+<script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new
Date();a=s.createElement(o),
+
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-41536543-1', 'uci.edu');
+ ga('send', 'pageview');</script>
+
+ </head>
+ <body class="topBarDisabled">
+
+
+
+
+ <div class="container-fluid">
+ <div id="banner">
+ <div class="pull-left">
+ <a href=".././"
id="bannerLeft">
+
<img src="../images/asterixlogo.png" alt="AsterixDB"/>
+ </a>
+ </div>
+ <div class="pull-right"> </div>
+ <div class="clear"><hr/></div>
+ </div>
+
+ <div id="breadcrumbs">
+ <ul class="breadcrumb">
+
+
+ <li id="publishDate">Last Published: 2017-04-24</li>
+
+
+
+ <li id="projectVersion" class="pull-right">Version: 0.9.1</li>
+
+ <li class="divider
pull-right">|</li>
+
+ <li class="pull-right"> <a href="../index.html"
title="Documentation Home">
+ Documentation Home</a>
+ </li>
+
+ </ul>
+ </div>
+
+
+ <div class="row-fluid">
+ <div id="leftColumn" class="span3">
+ <div class="well sidebar-nav">
+
+
+ <ul class="nav nav-list">
+ <li class="nav-header">Get Started - Installation</li>
+
+ <li>
+
+ <a href="../ncservice.html" title="Option 1: using
NCService">
+ <i class="none"></i>
+ Option 1: using NCService</a>
+ </li>
+
+ <li>
+
+ <a href="../ansible.html" title="Option 2: using
Ansible">
+ <i class="none"></i>
+ Option 2: using Ansible</a>
+ </li>
+
+ <li>
+
+ <a href="../aws.html" title="Option 3: using Amazon
Web Services">
+ <i class="none"></i>
+ Option 3: using Amazon Web Services</a>
+ </li>
+
+ <li>
+
+ <a href="../yarn.html" title="Option 4: using YARN">
+ <i class="none"></i>
+ Option 4: using YARN</a>
+ </li>
+
+ <li>
+
+ <a href="../install.html" title="Option 5: using
Managix (deprecated)">
+ <i class="none"></i>
+ Option 5: using Managix (deprecated)</a>
+ </li>
+ <li class="nav-header">AsterixDB Primer</li>
+
+ <li>
+
+ <a href="../sqlpp/primer-sqlpp.html" title="Option
1: using SQL++">
+ <i class="none"></i>
+ Option 1: using SQL++</a>
+ </li>
+
+ <li>
+
+ <a href="../aql/primer.html" title="Option 2: using
AQL">
+ <i class="none"></i>
+ Option 2: using AQL</a>
+ </li>
+ <li class="nav-header">Data Model</li>
+
+ <li>
+
+ <a href="../datamodel.html" title="The Asterix Data
Model">
+ <i class="none"></i>
+ The Asterix Data Model</a>
+ </li>
+ <li class="nav-header">Queries - SQL++</li>
+
+ <li>
+
+ <a href="../sqlpp/manual.html" title="The SQL++
Query Language">
+ <i class="none"></i>
+ The SQL++ Query Language</a>
+ </li>
+
+ <li>
+
+ <a href="../sqlpp/builtins.html" title="Builtin
Functions">
+ <i class="none"></i>
+ Builtin Functions</a>
+ </li>
+ <li class="nav-header">Queries - AQL</li>
+
+ <li class="active">
+
+ <a href="#"><i class="none"></i>The Asterix Query Language
(AQL)</a>
+ </li>
+
+ <li>
+
+ <a href="../aql/builtins.html" title="Builtin
Functions">
+ <i class="none"></i>
+ Builtin Functions</a>
+ </li>
+ <li class="nav-header">API/SDK</li>
+
+ <li>
+
+ <a href="../api.html" title="HTTP API">
+ <i class="none"></i>
+ HTTP API</a>
+ </li>
+
+ <li>
+
+ <a href="../csv.html" title="CSV Output">
+ <i class="none"></i>
+ CSV Output</a>
+ </li>
+ <li class="nav-header">Advanced Features</li>
+
+ <li>
+
+ <a href="../aql/fulltext.html" title="Support of
Full-text Queries">
+ <i class="none"></i>
+ Support of Full-text Queries</a>
+ </li>
+
+ <li>
+
+ <a href="../aql/externaldata.html" title="Accessing
External Data">
+ <i class="none"></i>
+ Accessing External Data</a>
+ </li>
+
+ <li>
+
+ <a href="../feeds/tutorial.html" title="Support for
Data Ingestion">
+ <i class="none"></i>
+ Support for Data Ingestion</a>
+ </li>
+
+ <li>
+
+ <a href="../udf.html" title="User Defined Functions">
+ <i class="none"></i>
+ User Defined Functions</a>
+ </li>
+
+ <li>
+
+ <a href="../aql/filters.html" title="Filter-Based
LSM Index Acceleration">
+ <i class="none"></i>
+ Filter-Based LSM Index Acceleration</a>
+ </li>
+
+ <li>
+
+ <a href="../aql/similarity.html" title="Support of
Similarity Queries">
+ <i class="none"></i>
+ Support of Similarity Queries</a>
+ </li>
+ </ul>
+
+
+
+ <hr class="divider" />
+
+ <div id="poweredBy">
+ <div class="clear"></div>
+ <div class="clear"></div>
+ <div class="clear"></div>
+
<a href=".././" title="AsterixDB"
class="builtBy">
+ <img class="builtBy" alt="AsterixDB" src="../images/asterixlogo.png"
/>
+ </a>
+ </div>
+ </div>
+ </div>
+
+
+ <div id="bodyColumn" class="span9" >
+
+ <!-- ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing,
+ ! software distributed under the License is distributed on an
+ ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ! KIND, either express or implied. See the License for the
+ ! specific language governing permissions and limitations
+ ! under the License.
+ ! --><h1>The Asterix Query Language, Version 1.0</h1>
+<div class="section">
+<h2><a name="Table_of_Contents"></a><a name="toc" id="toc">Table of
Contents</a></h2>
+
+<ul>
+
+<li><a href="#Introduction">1. Introduction</a></li>
+
+<li><a href="#Expressions">2. Expressions</a></li>
+
+<li><a href="#Statements">3. Statements</a></li>
+</ul></div>
+<div class="section">
+<h2><a name="a1._Introduction_Back_to_TOC"></a><a name="Introduction"
id="Introduction">1. Introduction</a><font size="4"> <a href="#toc">[Back to
TOC]</a></font></h2>
+<p>This document is intended as a reference guide to the full syntax and
semantics of the Asterix Query Language (AQL), the language for talking to
AsterixDB. This guide covers both the data manipulation language (DML) aspects
of AQL, including its support for queries and data modification, as well as its
data definition language (DDL) aspects. New AsterixDB users are encouraged to
read and work through the (friendlier) guide “AsterixDB 101: An ADM and
AQL Primer” before attempting to make use of this document. In addition,
readers are advised to read and understand the Asterix Data Model (ADM)
reference guide since a basic understanding of ADM concepts is a prerequisite
to understanding AQL. In what follows, we detail the features of the AQL
language in a grammar-guided manner: We list and briefly explain each of the
productions in the AQL grammar, offering examples for clarity in cases where
doing so seems needed or helpful.</p></div>
+<div class="section">
+<h2><a name="a2._Expressions_Back_to_TOC"></a><a name="Expressions"
id="Expressions">2. Expressions</a> <font size="4"><a href="#toc">[Back to
TOC]</a></font></h2>
+
+<div class="source">
+<div class="source">
+<pre>Query ::= Expression
+</pre></div></div>
+<p>An AQL query can be any legal AQL expression.</p>
+
+<div class="source">
+<div class="source">
+<pre>Expression ::= ( OperatorExpr | IfThenElse | FLWOR | QuantifiedExpression
)
+</pre></div></div>
+<p>AQL is a fully composable expression language. Each AQL expression returns
zero or more Asterix Data Model (ADM) instances. There are four major kinds of
expressions in AQL. At the topmost level, an AQL expression can be an
OperatorExpr (similar to a mathematical expression), an IfThenElse (to choose
between two alternative values), a FLWOR expression (the heart of AQL,
pronounced “flower expression”), or a QuantifiedExpression (which
yields a boolean value). Each will be detailed as we explore the full AQL
grammar.</p>
+<div class="section">
+<h3><a name="Primary_Expressions"></a>Primary Expressions</h3>
+
+<div class="source">
+<div class="source">
+<pre>PrimaryExpr ::= Literal
+ | VariableRef
+ | ParenthesizedExpression
+ | FunctionCallExpr
+ | DatasetAccessExpression
+ | ListConstructor
+ | ObjectConstructor
+</pre></div></div>
+<p>The most basic building block for any AQL expression is the PrimaryExpr.
This can be a simple literal (constant) value, a reference to a query variable
that is in scope, a parenthesized expression, a function call, an expression
accessing the ADM contents of a dataset, a newly constructed list of ADM
instances, or a newly constructed ADM object.</p>
+<div class="section">
+<h4><a name="Literals"></a>Literals</h4>
+
+<div class="source">
+<div class="source">
+<pre>Literal ::= StringLiteral
+ | IntegerLiteral
+ | FloatLiteral
+ | DoubleLiteral
+ | "null"
+ | "true"
+ | "false"
+StringLiteral ::= ("\"" (<ESCAPE_QUOT> |
~["\""])* "\"")
+ | ("\'" (<ESCAPE_APOS> | ~["\'"])*
"\'")
+<ESCAPE_QUOT> ::= "\\\""
+<ESCAPE_APOS> ::= "\\\'"
+IntegerLiteral ::= <DIGITS>
+<DIGITS> ::= ["0" - "9"]+
+FloatLiteral ::= <DIGITS> ( "f" | "F" )
+ | <DIGITS> ( "." <DIGITS> (
"f" | "F" ) )?
+ | "." <DIGITS> ( "f" |
"F" )
+DoubleLiteral ::= <DIGITS>
+ | <DIGITS> ( "." <DIGITS> )?
+ | "." <DIGITS>
+</pre></div></div>
+<p>Literals (constants) in AQL can be strings, integers, floating point
values, double values, boolean constants, or the constant value null. The null
value in AQL has “unknown” or “missing” value
semantics, similar to (though not identical to) nulls in the relational query
language SQL.</p>
+<p>The following are some simple examples of AQL literals. Since AQL is an
expression language, each example is also a complete, legal AQL query (!).</p>
+<div class="section">
+<h5><a name="Examples"></a>Examples</h5>
+
+<div class="source">
+<div class="source">
+<pre>"a string"
+42
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Variable_References"></a>Variable References</h4>
+
+<div class="source">
+<div class="source">
+<pre>VariableRef ::= <VARIABLE>
+<VARIABLE> ::= "$" <LETTER> (<LETTER> |
<DIGIT> | "_")*
+<LETTER> ::= ["A" - "Z", "a" -
"z"]
+</pre></div></div>
+<p>A variable in AQL can be bound to any legal ADM value. A variable reference
refers to the value to which an in-scope variable is bound. (E.g., a variable
binding may originate from one of the for or let clauses of a FLWOR expression
or from an input parameter in the context of an AQL function body.)</p>
+<div class="section">
+<h5><a name="Examples"></a>Examples</h5>
+
+<div class="source">
+<div class="source">
+<pre>$tweet
+$id
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Parenthesized_Expressions"></a>Parenthesized Expressions</h4>
+
+<div class="source">
+<div class="source">
+<pre>ParenthesizedExpression ::= "(" Expression ")"
+</pre></div></div>
+<p>As in most languages, an expression may be parenthesized.</p>
+<p>Since AQL is an expression language, the following example expression is
actually also a complete, legal AQL query whose result is the value 2. (As
such, you can have Big Fun explaining to your boss how AsterixDB and AQL can
turn your 1000-node shared-nothing Big Data cluster into a $5M calculator in
its spare time.)</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>( 1 + 1 )
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Function_Calls"></a>Function Calls</h4>
+
+<div class="source">
+<div class="source">
+<pre>FunctionCallExpr ::= FunctionOrTypeName "(" ( Expression (
"," Expression )* )? ")"
+</pre></div></div>
+<p>Functions are included in AQL, like most languages, as a way to package
useful functionality or to componentize complicated or reusable AQL
computations. A function call is a legal AQL query expression that represents
the ADM value resulting from the evaluation of its body expression with the
given parameter bindings; the parameter value bindings can themselves be any
AQL expressions.</p>
+<p>The following example is a (built-in) function call expression whose value
is 8.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>string-length("a string")
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Dataset_Access"></a>Dataset Access</h4>
+
+<div class="source">
+<div class="source">
+<pre>DatasetAccessExpression ::= "dataset" ( ( Identifier (
"." Identifier )? )
+ | ( "(" Expression ")" ) )
+Identifier ::= <IDENTIFIER> | StringLiteral
+<IDENTIFIER> ::= <LETTER> (<LETTER> |
<DIGIT> | <SPECIALCHARS>)*
+<SPECIALCHARS> ::= ["$", "_", "-"]
+</pre></div></div>
+<p>Querying Big Data is the main point of AsterixDB and AQL. Data in AsterixDB
reside in datasets (collections of ADM objects), each of which in turn resides
in some namespace known as a dataverse (data universe). Data access in a query
expression is accomplished via a DatasetAccessExpression. Dataset access
expressions are most commonly used in FLWOR expressions, where variables are
bound to their contents.</p>
+<p>Note that the Identifier that identifies a dataset (or any other Identifier
in AQL) can also be a StringLiteral. This is especially useful to avoid
conficts with AQL keywords (e.g. “dataset”, “null”,
or “type”).</p>
+<p>The following are three examples of legal dataset access expressions. The
first one accesses a dataset called Customers in the dataverse called SalesDV.
The second one accesses the Customers dataverse in whatever the current
dataverse is. The third one does the same thing as the second but uses a
slightly older AQL syntax.</p>
+<div class="section">
+<h5><a name="Examples"></a>Examples</h5>
+
+<div class="source">
+<div class="source">
+<pre>dataset SalesDV.Customers
+dataset Customers
+dataset("Customers")
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Constructors"></a>Constructors</h4>
+
+<div class="source">
+<div class="source">
+<pre>ListConstructor ::= ( OrderedListConstructor |
UnorderedListConstructor )
+OrderedListConstructor ::= "[" ( Expression ( ","
Expression )* )? "]"
+UnorderedListConstructor ::= "{{" ( Expression ( ","
Expression )* )? "}}"
+ObjectConstructor ::= "{" ( FieldBinding ( ","
FieldBinding )* )? "}"
+FieldBinding ::= Expression ":" Expression
+</pre></div></div>
+<p>A major feature of AQL is its ability to construct new ADM data instances.
This is accomplished using its constructors for each of the major ADM complex
object structures, namely lists (ordered or unordered) and objects. Ordered
lists are like JSON arrays, while unordered lists have bag (multiset)
semantics. Objects are built from attributes that are field-name/field-value
pairs, again like JSON. (See the AsterixDB Data Model document for more details
on each.)</p>
+<p>The following examples illustrate how to construct a new ordered list with
3 items, a new unordered list with 4 items, and a new object with 2 fields,
respectively. List elements can be homogeneous (as in the first example), which
is the common case, or they may be heterogeneous (as in the second example).
The data values and field name values used to construct lists and objects in
constructors are all simply AQL expressions. Thus the list elements, field
names, and field values used in constructors can be simple literals (as in
these three examples) or they can come from query variable references or even
arbitrarily complex AQL expressions.</p>
+<div class="section">
+<h5><a name="Examples"></a>Examples</h5>
+
+<div class="source">
+<div class="source">
+<pre>[ "a", "b", "c" ]
+
+{{ 42, "forty-two", "AsterixDB!", 3.14f }}
+
+{
+ "project name": "AsterixDB"
+ "project members": {{ "vinayakb", "dtabass",
"chenli" }}
+}
+</pre></div></div></div>
+<div class="section">
+<h5><a name="Note"></a>Note</h5>
+<p>When constructing nested objects there needs to be a space between the
closing braces to avoid confusion with the <tt>}}</tt> token that ends an
unordered list constructor: <tt>{ "a" : { "b" :
"c" }}</tt> will fail to parse while <tt>{ "a" : {
"b" : "c" } }</tt> will work.</p></div></div></div>
+<div class="section">
+<h3><a name="Path_Expressions"></a>Path Expressions</h3>
+
+<div class="source">
+<div class="source">
+<pre>ValueExpr ::= PrimaryExpr ( Field | Index )*
+Field ::= "." Identifier
+Index ::= "[" ( Expression | "?" ) "]"
+</pre></div></div>
+<p>Components of complex types in ADM are accessed via path expressions. Path
access can be applied to the result of an AQL expression that yields an
instance of such a type, e.g., a object or list instance. For objects, path
access is based on field names. For ordered lists, path access is based on
(zero-based) array-style indexing. AQL also supports an “I’m
feeling lucky” style index accessor, [?], for selecting an arbitrary
element from an ordered list. Attempts to access non-existent fields or list
elements produce a null (i.e., missing information) result as opposed to
signaling a runtime error.</p>
+<p>The following examples illustrate field access for a object, index-based
element access for an ordered list, and also a composition thereof.</p>
+<div class="section">
+<div class="section">
+<h5><a name="Examples"></a>Examples</h5>
+
+<div class="source">
+<div class="source">
+<pre>({"list": [ "a", "b", "c"]}).list
+
+(["a", "b", "c"])[2]
+
+({ "list": [ "a", "b", "c"]}).list[2]
+</pre></div></div></div></div></div>
+<div class="section">
+<h3><a name="Logical_Expressions"></a>Logical Expressions</h3>
+
+<div class="source">
+<div class="source">
+<pre>OperatorExpr ::= AndExpr ( "or" AndExpr )*
+AndExpr ::= RelExpr ( "and" RelExpr )*
+</pre></div></div>
+<p>As in most languages, boolean expressions can be built up from smaller
expressions by combining them with the logical connectives and/or. Legal
boolean values in AQL are true, false, and null. (Nulls in AQL are treated much
like SQL treats its unknown truth value in boolean expressions.)</p>
+<p>The following is an example of a conjuctive range predicate in AQL. It will
yield true if $a is bound to 4, null if $a is bound to null, and false
otherwise.</p>
+<div class="section">
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>$a > 3 and $a < 5
+</pre></div></div></div></div></div>
+<div class="section">
+<h3><a name="Comparison_Expressions"></a>Comparison Expressions</h3>
+
+<div class="source">
+<div class="source">
+<pre>RelExpr ::= AddExpr ( ( "<" | ">" |
"<=" | ">=" | "=" | "!=" |
"~=" ) AddExpr )?
+</pre></div></div>
+<p>AQL has the usual list of suspects, plus one, for comparing pairs of atomic
values. The “plus one” is the last operator listed above, which
is the “roughly equal” operator provided for similarity queries.
(See the separate document on <a href="similarity.html">AsterixDB Similarity
Queries</a> for more details on similarity matching.)</p>
+<p>An example comparison expression (which yields the boolean value true) is
shown below.</p>
+<div class="section">
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>5 > 3
+</pre></div></div></div></div></div>
+<div class="section">
+<h3><a name="Arithmetic_Expressions"></a>Arithmetic Expressions</h3>
+
+<div class="source">
+<div class="source">
+<pre>AddExpr ::= MultExpr ( ( "+" | "-" ) MultExpr )*
+MultExpr ::= UnaryExpr ( ( "*" | "/" | "%" |
"^"| "idiv" ) UnaryExpr )*
+UnaryExpr ::= ( ( "+" | "-" ) )? ValueExpr
+</pre></div></div>
+<p>AQL also supports the usual cast of characters for arithmetic expressions.
The example below evaluates to 25.</p>
+<div class="section">
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>3 ^ 2 + 4 ^ 2
+</pre></div></div></div></div></div>
+<div class="section">
+<h3><a name="FLWOR_Expression"></a>FLWOR Expression</h3>
+
+<div class="source">
+<div class="source">
+<pre>FLWOR ::= ( ForClause | LetClause ) ( Clause )*
("return"|"select") Expression
+Clause ::= ForClause | LetClause | WhereClause | OrderbyClause
+ | GroupClause | LimitClause | DistinctClause
+ForClause ::= ("for"|"from") Variable (
"at" Variable )? "in" ( Expression )
+LetClause ::= ("let"|"with") Variable ":="
Expression
+WhereClause ::= "where" Expression
+OrderbyClause ::= "order" "by" Expression ( (
"asc" ) | ( "desc" ) )?
+ ( "," Expression ( ( "asc" ) | (
"desc" ) )? )*
+GroupClause ::= "group" "by" ( Variable ":="
)? Expression ( "," ( Variable ":=" )? Expression )*
+ ("with"|"keeping") VariableRef (
"," VariableRef )*
+LimitClause ::= "limit" Expression ( "offset"
Expression )?
+DistinctClause ::= "distinct" "by" Expression (
"," Expression )*
+Variable ::= <VARIABLE>
+</pre></div></div>
+<p>The heart of AQL is the FLWOR (for-let-where-orderby-return) expression.
The roots of this expression were borrowed from the expression of the same name
in XQuery. A FLWOR expression starts with one or more clauses that establish
variable bindings. A <tt>for</tt> clause binds a variable incrementally to each
element of its associated expression; it includes an optional positional
variable for counting/numbering the bindings. By default no ordering is implied
or assumed by a <tt>for</tt> clause. A <tt>let</tt> clause binds a variable to
the collection of elements computed by its associated expression.</p>
+<p>Following the initial <tt>for</tt> or <tt>let</tt> clause(s), a FLWOR
expression may contain an arbitrary sequence of other clauses. The
<tt>where</tt> clause in a FLWOR expression filters the preceding bindings via
a boolean expression, much like a <tt>where</tt> clause does in a SQL query.
The <tt>order by</tt> clause in a FLWOR expression induces an ordering on the
data. The <tt>group by</tt> clause, discussed further below, forms groups based
on its group by expressions, optionally naming the expressions’ values
(which together form the grouping key for the expression). The <tt>with</tt>
subclause of a <tt>group by</tt> clause specifies the variable(s) whose values
should be grouped based on the grouping key(s); following the grouping clause,
only the grouping key(s) and the variables named in the with subclause remain
in scope, and the named grouping variables now contain lists formed from their
input values. The <tt>limit</tt> clause caps the number of values returne
d, optionally starting its result count from a specified offset. (Web
applications can use this feature for doing pagination.) The <tt>distinct</tt>
clause is similar to the <tt>group-by</tt> clause, but it forms no groups; it
serves only to eliminate duplicate values. As indicated by the grammar, the
clauses in an AQL query can appear in any order. To interpret a query, one can
think of data as flowing down through the query from the first clause to the
<tt>return</tt> clause.</p>
+<p>The following example shows a FLWOR expression that selects and returns one
user from the dataset FacebookUsers.</p>
+<div class="section">
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>for $user in dataset FacebookUsers
+where $user.id = 8
+return $user
+</pre></div></div>
+<p>The next example shows a FLWOR expression that joins two datasets,
FacebookUsers and FacebookMessages, returning user/message pairs. The results
contain one object per pair, with result objects containing the user’s
name and an entire message.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>for $user in dataset FacebookUsers
+for $message in dataset FacebookMessages
+where $message.author-id = $user.id
+return
+ {
+ "uname": $user.name,
+ "message": $message.message
+ };
+</pre></div></div>
+<p>In the next example, a <tt>let</tt> clause is used to bind a variable to
all of a user’s FacebookMessages. The query returns one object per user,
with result objects containing the user’s name and the set of all
messages by that user.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>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
+ };
+</pre></div></div>
+<p>The following example returns all TwitterUsers ordered by their followers
count (most followers first) and language. When ordering <tt>null</tt> is
treated as being smaller than any other value if <tt>null</tt>s are encountered
in the ordering key(s).</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre> for $user in dataset TwitterUsers
+ order by $user.followers_count desc, $user.lang asc
+ return $user
+</pre></div></div>
+<p>The next example illustrates the use of the <tt>group by</tt> clause in
AQL. After the <tt>group by</tt> clause in the query, only variables that are
either in the <tt>group by</tt> list or in the <tt>with</tt> list are in scope.
The variables in the clause’s <tt>with</tt> list will each contain a
collection of items following the <tt>group by</tt> clause; the collected items
are the values that the source variable was bound to in the tuples that formed
the group. For grouping <tt>null</tt> is handled as a single value.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre> for $x in dataset FacebookMessages
+ let $messages := $x.message
+ group by $loc := $x.sender-location with $messages
+ return
+ {
+ "location" : $loc,
+ "message" : $messages
+ }
+</pre></div></div>
+<p>The use of the <tt>limit</tt> clause is illustrated in the next
example.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre> for $user in dataset TwitterUsers
+ order by $user.followers_count desc
+ limit 2
+ return $user
+</pre></div></div>
+<p>The final example shows how AQL’s <tt>distinct by</tt> clause works.
Each variable in scope before the distinct clause is also in scope after the
<tt>distinct by</tt> clause. This clause works similarly to <tt>group by</tt>,
but for each variable that contains more than one value after the <tt>distinct
by</tt> clause, one value is picked nondeterministically. (If the variable is
in the <tt>distinct by</tt> list, then its value will be deterministic.) Nulls
are treated as a single value when they occur in a grouping field.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre> for $x in dataset FacebookMessages
+ distinct by $x.sender-location
+ return
+ {
+ "location" : $x.sender-location,
+ "message" : $x.message
+ }
+</pre></div></div>
+<p>In order to allow SQL fans to write queries in their favored ways, AQL
provides synonyms: <i>from</i> for <i>for</i>, <i>select</i> for <i>return</i>,
<i>with</i> for <i>let</i>, and <i>keeping</i> for <i>with</i> in the group by
clause. The following query is such an example.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre> from $x in dataset FacebookMessages
+ with $messages := $x.message
+ group by $loc := $x.sender-location keeping $messages
+ select
+ {
+ "location" : $loc,
+ "message" : $messages
+ }
+</pre></div></div></div></div></div>
+<div class="section">
+<h3><a name="Conditional_Expression"></a>Conditional Expression</h3>
+
+<div class="source">
+<div class="source">
+<pre>IfThenElse ::= "if" "(" Expression ")"
"then" Expression "else" Expression
+</pre></div></div>
+<p>A conditional expression is useful for choosing between two alternative
values based on a boolean condition. If its first (<tt>if</tt>) expression is
true, its second (<tt>then</tt>) expression’s value is returned, and
otherwise its third (<tt>else</tt>) expression is returned.</p>
+<p>The following example illustrates the form of a conditional expression.</p>
+<div class="section">
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>if (2 < 3) then "yes" else "no"
+</pre></div></div></div></div></div>
+<div class="section">
+<h3><a name="Quantified_Expressions"></a>Quantified Expressions</h3>
+
+<div class="source">
+<div class="source">
+<pre>QuantifiedExpression ::= ( ( "some" ) | ( "every" ) )
Variable "in" Expression
+ ( "," Variable "in" Expression )*
"satisfies" Expression
+</pre></div></div>
+<p>Quantified expressions are used for expressing existential or universal
predicates involving the elements of a collection.</p>
+<p>The following pair of examples illustrate the use of a quantified
expression to test that every (or some) element in the set [1, 2, 3] of
integers is less than three. The first example yields <tt>false</tt> and second
example yields <tt>true</tt>.</p>
+<p>It is useful to note that if the set were instead the empty set, the first
expression would yield <tt>true</tt> (“every” value in an empty
set satisfies the condition) while the second expression would yield
<tt>false</tt> (since there isn’t “some” value, as there
are no values in the set, that satisfies the condition).</p>
+<div class="section">
+<div class="section">
+<h5><a name="Examples"></a>Examples</h5>
+
+<div class="source">
+<div class="source">
+<pre>every $x in [ 1, 2, 3 ] satisfies $x < 3
+some $x in [ 1, 2, 3 ] satisfies $x < 3
+</pre></div></div></div></div></div></div>
+<div class="section">
+<h2><a name="a3._Statements_Back_to_TOC"></a><a name="Statements"
id="Statements">3. Statements</a> <font size="4"><a href="#toc">[Back to
TOC]</a></font></h2>
+
+<div class="source">
+<div class="source">
+<pre>Statement ::= ( SingleStatement ( ";" )? )* <EOF>
+SingleStatement ::= DataverseDeclaration
+ | FunctionDeclaration
+ | CreateStatement
+ | DropStatement
+ | LoadStatement
+ | SetStatement
+ | InsertStatement
+ | DeleteStatement
+ | UpsertStatement
+ | Query
+</pre></div></div>
+<p>In addition to expresssions for queries, AQL supports a variety of
statements for data definition and manipulation purposes as well as controlling
the context to be used in evaluating AQL expressions. AQL supports object-level
ACID transactions that begin and terminate implicitly for each object inserted,
deleted, upserted, or searched while a given AQL statement is being
executed.</p>
+<p>This section details the statements supported in the AQL language.</p>
+<div class="section">
+<h3><a name="Declarations"></a>Declarations</h3>
+
+<div class="source">
+<div class="source">
+<pre>DataverseDeclaration ::= "use" "dataverse" Identifier
+</pre></div></div>
+<p>The world of data in an AsterixDB cluster is organized into data namespaces
called dataverses. To set the default dataverse for a series of statements, the
use dataverse statement is provided.</p>
+<p>As an example, the following statement sets the default dataverse to be
TinySocial.</p>
+<div class="section">
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>use dataverse TinySocial;
+</pre></div></div>
+<p>The set statement in AQL is used to control aspects of the expression
evalation context for queries.</p>
+
+<div class="source">
+<div class="source">
+<pre>SetStatement ::= "set" Identifier StringLiteral
+</pre></div></div>
+<p>As an example, the following set statements request that Jaccard similarity
with a similarity threshold 0.6 be used for set similarity matching when the ~=
operator is used in a query expression.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>set simfunction "jaccard";
+set simthreshold "0.6f";
+</pre></div></div>
+<p>When writing a complex AQL query, it can sometimes be helpful to define one
or more auxilliary functions that each address a sub-piece of the overall
query. The declare function statement supports the creation of such helper
functions.</p>
+
+<div class="source">
+<div class="source">
+<pre>FunctionDeclaration ::= "declare" "function"
Identifier ParameterList "{" Expression "}"
+ParameterList ::= "(" ( <VARIABLE> ( ","
<VARIABLE> )* )? ")"
+</pre></div></div>
+<p>The following is a very simple example of a temporary AQL function
definition.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>declare function add($a, $b) {
+ $a + $b
+};
+</pre></div></div></div></div></div>
+<div class="section">
+<h3><a name="Lifecycle_Management_Statements"></a>Lifecycle Management
Statements</h3>
+
+<div class="source">
+<div class="source">
+<pre>CreateStatement ::= "create" ( DataverseSpecification
+ | TypeSpecification
+ | DatasetSpecification
+ | IndexSpecification
+ | FunctionSpecification )
+
+QualifiedName ::= Identifier ( "." Identifier )?
+DoubleQualifiedName ::= Identifier "." Identifier ( "."
Identifier )?
+</pre></div></div>
+<p>The create statement in AQL is used for creating persistent artifacts in
the context of dataverses. It can be used to create new dataverses, datatypes,
datasets, indexes, and user-defined AQL functions.</p>
+<div class="section">
+<h4><a name="Dataverses"></a>Dataverses</h4>
+
+<div class="source">
+<div class="source">
+<pre>DataverseSpecification ::= "dataverse" Identifier IfNotExists (
"with format" StringLiteral )?
+</pre></div></div>
+<p>The create dataverse statement is used to create new dataverses. To ease
the authoring of reusable AQL scripts, its optional IfNotExists clause allows
creation to be requested either unconditionally or only if the the dataverse
does not already exist. If this clause is absent, an error will be returned if
the specified dataverse already exists. The <tt>with format</tt> clause is a
placeholder for future functionality that can safely be ignored.</p>
+<p>The following example creates a dataverse named TinySocial.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create dataverse TinySocial;
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Types"></a>Types</h4>
+
+<div class="source">
+<div class="source">
+<pre>TypeSpecification ::= "type" FunctionOrTypeName IfNotExists
"as" TypeExpr
+FunctionOrTypeName ::= QualifiedName
+IfNotExists ::= ( "if not exists" )?
+TypeExpr ::= ObjectTypeDef | TypeReference | OrderedListTypeDef |
UnorderedListTypeDef
+ObjectTypeDef ::= ( "closed" | "open" )?
"{" ( ObjectField ( "," ObjectField )* )? "}"
+ObjectField ::= Identifier ":" ( TypeExpr ) ( "?"
)?
+NestedField ::= Identifier ( "." Identifier )*
+IndexField ::= NestedField ( ":" TypeReference )?
+TypeReference ::= Identifier
+OrderedListTypeDef ::= "[" ( TypeExpr ) "]"
+UnorderedListTypeDef ::= "{{" ( TypeExpr ) "}}"
+</pre></div></div>
+<p>The create type statement is used to create a new named ADM datatype. This
type can then be used to create datasets or utilized when defining one or more
other ADM datatypes. Much more information about the Asterix Data Model (ADM)
is available in the <a href="datamodel.html">data model reference guide</a> to
ADM. A new type can be a object type, a renaming of another type, an ordered
list type, or an unordered list type. A object type can be defined as being
either open or closed. Instances of a closed object type are not permitted to
contain fields other than those specified in the create type statement.
Instances of an open object type may carry additional fields, and open is the
default for a new type (if neither option is specified).</p>
+<p>The following example creates a new ADM object type called FacebookUser
type. Since it is closed, its instances will contain only what is specified in
the type definition. The first four fields are traditional typed name/value
pairs. The friend-ids field is an unordered list of 32-bit integers. The
employment field is an ordered list of instances of another named object type,
EmploymentType.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create type FacebookUserType as closed {
+ "id" : int32,
+ "alias" : string,
+ "name" : string,
+ "user-since" : datetime,
+ "friend-ids" : {{ int32 }},
+ "employment" : [ EmploymentType ]
+}
+</pre></div></div>
+<p>The next example creates a new ADM object type called FbUserType. Note that
the type of the id field is UUID. You need to use this field type if you want
to have this field be an autogenerated-PK field. Refer to the Datasets section
later for more details.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create type FbUserType as closed {
+ "id" : uuid,
+ "alias" : string,
+ "name" : string
+}
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Datasets"></a>Datasets</h4>
+
+<div class="source">
+<div class="source">
+<pre>DatasetSpecification ::= "internal"? "dataset"
QualifiedName "(" QualifiedName ")" IfNotExists
+ PrimaryKey ( "on" Identifier )? (
"hints" Properties )?
+ ( "using" "compaction"
"policy" CompactionPolicy ( Configuration )? )?
+ ( "with filter on" Identifier )?
+ | "external" "dataset"
QualifiedName "(" QualifiedName ")" IfNotExists
+ "using" AdapterName Configuration (
"hints" Properties )?
+ ( "using" "compaction"
"policy" CompactionPolicy ( Configuration )? )?
+AdapterName ::= Identifier
+Configuration ::= "(" ( KeyValuePair ( ","
KeyValuePair )* )? ")"
+KeyValuePair ::= "(" StringLiteral "="
StringLiteral ")"
+Properties ::= ( "(" Property ( "," Property )*
")" )?
+Property ::= Identifier "=" ( StringLiteral |
IntegerLiteral )
+FunctionSignature ::= FunctionOrTypeName "@" IntegerLiteral
+PrimaryKey ::= "primary" "key" NestedField (
"," NestedField )* ( "autogenerated ")?
+CompactionPolicy ::= Identifier
+PrimaryKey ::= "primary" "key" Identifier (
"," Identifier )* ( "autogenerated ")?
+</pre></div></div>
+<p>The create dataset statement is used to create a new dataset. Datasets are
named, unordered collections of ADM object instances; they are where data lives
persistently and are the targets for queries in AsterixDB. Datasets are typed,
and AsterixDB will ensure that their contents conform to their type
definitions. An Internal dataset (the default) is a dataset that is stored in
and managed by AsterixDB. It must have a specified unique primary key that can
be used to partition data across nodes of an AsterixDB cluster. The primary key
is also used in secondary indexes to uniquely identify the indexed primary data
objects. Random primary key (UUID) values can be auto-generated by declaring
the field to be UUID and putting “autogenerated” after the
“primary key” identifier. In this case, values for the
auto-generated PK field should not be provided by the user since it will be
auto-generated by AsterixDB. Optionally, a filter can be created on a field to f
urther optimize range queries with predicates on the filter’s field.
(Refer to <a href="filters.html">Filter-Based LSM Index Acceleration</a> for
more information about filters.)</p>
+<p>An External dataset is stored outside of AsterixDB (currently datasets in
HDFS or on the local filesystem(s) of the cluster’s nodes are
supported). External dataset support allows AQL queries to treat external data
as though it were stored in AsterixDB, making it possible to query
“legacy” file data (e.g., Hive data) without having to physically
import it into AsterixDB. For an external dataset, an appropriate adapter must
be selected to handle the nature of the desired external data. (See the <a
href="externaldata.html">guide to external data</a> for more information on the
available adapters.)</p>
+<p>When creating a dataset, it is possible to choose a merge policy that
controls which of the underlaying LSM storage components to be merged.
Currently, AsterixDB provides four different merge policies that can be
configured per dataset: no-merge, constant, prefix, and correlated-prefix. The
no-merge policy simply never merges disk components. While the constant policy
merges disk components when the number of components reaches some constant
number k, which can be configured by the user. The prefix policy relies on
component sizes and the number of components to decide which components to
merge. Specifically, it works by first trying to identify the smallest ordered
(oldest to newest) sequence of components such that the sequence does not
contain a single component that exceeds some threshold size M and that either
the sum of the component’s sizes exceeds M or the number of components
in the sequence exceeds another threshold C. If such a sequence of components
exists, the
n each of the components in the sequence are merged together to form a single
component. Finally, the correlated-prefix is similar to the prefix policy but
it delegates the decision of merging the disk components of all the indexes in
a dataset to the primary index. When the policy decides that the primary index
needs to be merged (using the same decision criteria as for the prefix policy),
then it will issue successive merge requests on behalf of all other indexes
associated with the same dataset. The default policy for AsterixDB is the
prefix policy except when there is a filter on a dataset, where the preferred
policy for filters is the correlated-prefix.</p>
+<p>The following example creates an internal dataset for storing
FacefookUserType objects. It specifies that their id field is their primary
key.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create internal dataset FacebookUsers(FacebookUserType) primary key id;
+</pre></div></div>
+<p>The following example creates an internal dataset for storing FbUserType
objects. It specifies that their id field is their primary key. It also
specifies that the id field is an auto-generated field, meaning that a randomly
generated UUID value will be assigned to each object by the system. (A user
should therefore not proivde a value for this field.) Note that the id field
should be UUID.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create internal dataset FbMsgs(FbUserType) primary key id autogenerated;
+</pre></div></div>
+<p>The next example creates an external dataset for storing LineitemType
objects. The choice of the <tt>hdfs</tt> adapter means that its data will
reside in HDFS. The create statement provides parameters used by the hdfs
adapter: the URL and path needed to locate the data in HDFS and a description
of the data format.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create external dataset Lineitem('LineitemType) using hdfs (
+ ("hdfs"="hdfs://HOST:PORT"),
+ ("path"="HDFS_PATH"),
+ ("input-format"="text-input-format"),
+ ("format"="delimited-text"),
+ ("delimiter"="|"));
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Indices"></a>Indices</h4>
+
+<div class="source">
+<div class="source">
+<pre>IndexSpecification ::= "index" Identifier IfNotExists
"on" QualifiedName
+ "(" ( IndexField ) ( "," IndexField
)* ")" ( "type" IndexType )? ( "enforced" )?
+IndexType ::= "btree"
+ | "rtree"
+ | "keyword"
+ | "ngram" "(" IntegerLiteral
")"
+ | "fulltext"
+</pre></div></div>
+<p>The create index statement creates a secondary index on one or more fields
of a specified dataset. Supported index types include <tt>btree</tt> for
totally ordered datatypes, <tt>rtree</tt> for spatial data, and
<tt>keyword</tt>, <tt>ngram</tt>, and <tt>fulltext</tt> for textual (string)
data. An index can be created on a nested field (or fields) by providing a
valid path expression as an index field identifier. An index field is not
required to be part of the datatype associated with a dataset if that datatype
is declared as open and the field’s type is provided along with its type
and the <tt>enforced</tt> keyword is specified in the end of index definition.
<tt>Enforcing</tt> an open field will introduce a check that will make sure
that the actual type of an indexed field (if the field exists in the object)
always matches this specified (open) field type.</p>
+<p>The following example creates a btree index called fbAuthorIdx on the
author-id field of the FacebookMessages dataset. This index can be useful for
accelerating exact-match queries, range search queries, and joins involving the
author-id field.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create index fbAuthorIdx on FacebookMessages(author-id) type btree;
+</pre></div></div>
+<p>The following example creates an open btree index called fbSendTimeIdx on
the open send-time field of the FacebookMessages dataset having datetime type.
This index can be useful for accelerating exact-match queries, range search
queries, and joins involving the send-time field.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create index fbSendTimeIdx on FacebookMessages(send-time:datetime) type
btree enforced;
+</pre></div></div>
+<p>The following example creates a btree index called twUserScrNameIdx on the
screen-name field, which is a nested field of the user field in the
TweetMessages dataset. This index can be useful for accelerating exact-match
queries, range search queries, and joins involving the screen-name
field.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create index twUserScrNameIdx on TweetMessages(user.screen-name) type
btree;
+</pre></div></div>
+<p>The following example creates an rtree index called fbSenderLocIdx on the
sender-location field of the FacebookMessages dataset. This index can be useful
for accelerating queries that use the <a
href="functions.html#spatial-intersect"><tt>spatial-intersect</tt> function</a>
in a predicate involving the sender-location field.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create index fbSenderLocIndex on FacebookMessages(sender-location) type
rtree;
+</pre></div></div>
+<p>The following example creates a 3-gram index called fbUserIdx on the name
field of the FacebookUsers dataset. This index can be used to accelerate some
similarity or substring maching queries on the name field. For details refer to
the <a href="similarity.html#NGram_Index">document on similarity
queries</a>.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create index fbUserIdx on FacebookUsers(name) type ngram(3);
+</pre></div></div>
+<p>The following example creates a keyword index called fbMessageIdx on the
message field of the FacebookMessages dataset. This keyword index can be used
to optimize queries with token-based similarity predicates on the message
field. For details refer to the <a
href="similarity.html#Keyword_Index">document on similarity
queries</a>.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create index fbMessageIdx on FacebookMessages(message) type keyword;
+</pre></div></div>
+<p>The following example creates a full-text index called fbMessageIdx on the
message field of the FacebookMessages dataset. This full-text index can be used
to optimize queries with full-text search predicates on the message field. For
details refer to the <a href="fulltext.html#toc">document on full-text
queries</a>.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create index fbMessageIdx on FacebookMessages(message) type fulltext;
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Functions"></a>Functions</h4>
+<p>The create function statement creates a named function that can then be
used and reused in AQL queries. The body of a function can be any AQL
expression involving the function’s parameters.</p>
+
+<div class="source">
+<div class="source">
+<pre>FunctionSpecification ::= "function" FunctionOrTypeName
IfNotExists ParameterList "{" Expression "}"
+</pre></div></div>
+<p>The following is a very simple example of a create function statement. It
differs from the declare function example shown previously in that it results
in a function that is persistently registered by name in the specified
dataverse.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>create function add($a, $b) {
+ $a + $b
+};
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Removal"></a>Removal</h4>
+
+<div class="source">
+<div class="source">
+<pre>DropStatement ::= "drop" ( "dataverse"
Identifier IfExists
+ | "type" FunctionOrTypeName IfExists
+ | "dataset" QualifiedName IfExists
+ | "index" DoubleQualifiedName IfExists
+ | "function" FunctionSignature
IfExists )
+IfExists ::= ( "if" "exists" )?
+</pre></div></div>
+<p>The drop statement in AQL is the inverse of the create statement. It can be
used to drop dataverses, datatypes, datasets, indexes, and functions.</p>
+<p>The following examples illustrate uses of the drop statement.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>drop dataset FacebookUsers if exists;
+
+drop index FacebookUsers.fbSenderLocIndex;
+
+drop type FacebookUserType;
+
+drop dataverse TinySocial;
+
+drop function add;
+</pre></div></div></div></div></div>
+<div class="section">
+<h3><a name="ImportExport_Statements"></a>Import/Export Statements</h3>
+
+<div class="source">
+<div class="source">
+<pre>LoadStatement ::= "load" "dataset" QualifiedName
"using" AdapterName Configuration ( "pre-sorted" )?
+</pre></div></div>
+<p>The load statement is used to initially populate a dataset via bulk loading
of data from an external file. An appropriate adapter must be selected to
handle the nature of the desired external data. The load statement accepts the
same adapters and the same parameters as external datasets. (See the <a
href="externaldata.html">guide to external data</a> for more information on the
available adapters.) If a dataset has an auto-generated primary key field, a
file to be imported should not include that field in it.</p>
+<p>The following example shows how to bulk load the FacebookUsers dataset from
an external file containing data that has been prepared in ADM format.</p>
+<div class="section">
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>load dataset FacebookUsers using localfs
+(("path"="localhost:///Users/zuck/AsterixDB/load/fbu.adm"),("format"="adm"));
+</pre></div></div></div></div></div>
+<div class="section">
+<h3><a name="Modification_Statements"></a>Modification Statements</h3>
+<div class="section">
+<h4><a name="Insert"></a>Insert</h4>
+
+<div class="source">
+<div class="source">
+<pre>InsertStatement ::= "insert" "into"
"dataset" QualifiedName ( "as" Variable )? Query (
"returning" Query )?
+</pre></div></div>
+<p>The AQL insert statement is used to insert data into a dataset. The data to
be inserted comes from an AQL query expression. The expression can be as simple
as a constant expression, or in general it can be any legal AQL query. Inserts
in AsterixDB are processed transactionally, with the scope of each insert
transaction being the insertion of a single object plus its affiliated
secondary index entries (if any). If the query part of an insert returns a
single object, then the insert statement itself will be a single, atomic
transaction. If the query part returns multiple objects, then each object
inserted will be handled independently as a tranaction. If a dataset has an
auto-generated primary key field, an insert statement should not include a
value for that field in it. (The system will automatically extend the provided
object with this additional field and a corresponding value.). The optional
“as Variable” provides a variable binding for the inserted
objects, whic
h can be used in the “returning” clause. The optional
“returning Query” allows users to run simple queries/functions on
the objects returned by the insert. This query cannot refer to any datasets.</p>
+<p>The following example illustrates a query-based insertion.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>insert into dataset UsersCopy as $inserted (for $user in dataset
FacebookUsers return $user ) returning $inserted.screen-name
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Delete"></a>Delete</h4>
+
+<div class="source">
+<div class="source">
+<pre>DeleteStatement ::= "delete" Variable "from"
"dataset" QualifiedName ( "where" Expression )?
+</pre></div></div>
+<p>The AQL delete statement is used to delete data from a target dataset. The
data to be deleted is identified by a boolean expression involving the variable
bound to the target dataset in the delete statement. Deletes in AsterixDB are
processed transactionally, with the scope of each delete transaction being the
deletion of a single object plus its affiliated secondary index entries (if
any). If the boolean expression for a delete identifies a single object, then
the delete statement itself will be a single, atomic transaction. If the
expression identifies multiple objects, then each object deleted will be
handled independently as a transaction.</p>
+<p>The following example illustrates a single-object deletion.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>delete $user from dataset FacebookUsers where $user.id = 8;
+</pre></div></div></div></div>
+<div class="section">
+<h4><a name="Upsert"></a>Upsert</h4>
+
+<div class="source">
+<div class="source">
+<pre>UpsertStatement ::= "upsert" "into"
"dataset" QualifiedName Query
+</pre></div></div>
+<p>The AQL upsert statement is used to couple delete (if found) with insert
data into a dataset. The data to be upserted comes from an AQL query
expression. The expression can be as simple as a constant expression, or in
general it can be any legal AQL query. Upserts in AsterixDB are processed
transactionally, with the scope of each upsert transaction being the upsertion
(deletion if found + insertion) of a single object plus its affiliated
secondary index entries (if any). If the query part of an upsert returns a
single object, then the upsert statement itself will be a single, atomic
transaction. If the query part returns multiple objects, then each object
upserted will be handled independently as a tranaction.</p>
+<p>The following example illustrates a query-based upsertion.</p>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>upsert into dataset Users (for $user in dataset FacebookUsers return
$user)
+</pre></div></div>
+<p>We close this guide to AQL with one final example of a query
expression.</p></div>
+<div class="section">
+<h5><a name="Example"></a>Example</h5>
+
+<div class="source">
+<div class="source">
+<pre>for $praise in {{ "great", "brilliant",
"awesome" }}
+return
+ string-concat(["AsterixDB is ", $praise])
+</pre></div></div></div></div></div></div>
+ </div>
+ </div>
+ </div>
+
+ <hr/>
+
+ <footer>
+ <div class="container-fluid">
+ <div class="row span12">Copyright © 2017
+ <a href="https://www.apache.org/";>The Apache Software
Foundation</a>.
+ All Rights Reserved.
+
+ </div>
+
+ <?xml
version="1.0" encoding="UTF-8"?>
+<div class="row-fluid">Apache AsterixDB, AsterixDB, Apache, the Apache
+ feather logo, and the Apache AsterixDB project logo are either
+ registered trademarks or trademarks of The Apache Software
+ Foundation in the United States and other countries.
+ All other marks mentioned may be trademarks or registered
+ trademarks of their respective owners.</div>
+
+
+ </div>
+ </footer>
+ </body>
+</html>
