Make terminologies consistent in docs.
Change-Id: I35a647601441a48bb5576b115324fb0dc6eae176
Reviewed-on: https://asterix-gerrit.ics.uci.edu/1258
Sonar-Qube: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Tested-by: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Integration-Tests: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Reviewed-by: Till Westmann <tillw@apache.org>
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 7641b92..2733679 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/2_expr.md
@@ -29,9 +29,11 @@
| VariableReference
| ParenthesizedExpression
| FunctionCallExpression
- | Constructor
+ | Constructor
-The most basic building block for any SQL++ expression is PrimaryExpression. This can be a simple literal (constant) value, a reference to a query variable that is in scope, a parenthesized expression, a function call, or a newly constructed instance of the data model (such as a newly constructed record or list of data model instances).
+The most basic building block for any SQL++ expression is PrimaryExpression. This can be a simple literal (constant)
+value, a reference to a query variable that is in scope, a parenthesized expression, a function call, or a newly
+constructed instance of the data model (such as a newly constructed record, array, or multiset of data model instances).
### <a id="Literals">Literals</a>
@@ -70,9 +72,9 @@
### <a id="Variable_references">Variable References</a>
- VariableReference ::= <IDENTIFIER>|<DelimitedIdentifier>
- <IDENTIFIER> ::= <LETTER> (<LETTER> | <DIGIT> | "_" | "$")*
- <LETTER> ::= ["A" - "Z", "a" - "z"]
+ VariableReference ::= <IDENTIFIER>|<DelimitedIdentifier>
+ <IDENTIFIER> ::= <LETTER> (<LETTER> | <DIGIT> | "_" | "$")*
+ <LETTER> ::= ["A" - "Z", "a" - "z"]
DelimitedIdentifier ::= "\`" (<ESCAPE_APOS> | ~["\'"])* "\`"
A variable in SQL++ can be bound to any legal data model 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 `FROM`, `WITH` or `LET` clauses of a `SELECT` statement or from an input parameter in the context of a function body.) Backticks, e.g., \`id\`, are used for delimited identifiers. Delimiting is needed when a variable's desired name clashes with a SQL++ keyword or includes characters not allowed in regular identifiers.
@@ -110,15 +112,25 @@
### <a id="Constructors">Constructors</a>
- ListConstructor ::= OrderedListConstructor | UnorderedListConstructor
- OrderedListConstructor ::= "[" ( Expression ( "," Expression )* )? "]"
- UnorderedListConstructor ::= "{{" ( Expression ( "," Expression )* )? "}}"
+ CollectionConstructor ::= ArrayConstructor | MultisetConstructor
+ ArrayConstructor ::= "[" ( Expression ( "," Expression )* )? "]"
+ MultisetConstructor ::= "{{" ( Expression ( "," Expression )* )? "}}"
RecordConstructor ::= "{" ( FieldBinding ( "," FieldBinding )* )? "}"
FieldBinding ::= Expression ":" Expression
-A major feature of SQL++ is its ability to construct new data model instances. This is accomplished using its constructors for each of the model's complex object structures, namely lists (ordered or unordered) and records. Ordered lists are like JSON arrays, while unordered lists have multiset (bag) semantics. Records are built from attributes that are field-name/field-value pairs, again like JSON. (See the data model document for more details on each.)
+A major feature of SQL++ is its ability to construct new data model instances. This is accomplished using its constructors
+for each of the model's complex object structures, namely arrays, multisets, and records.
+Arrays are like JSON arrays, while multisets have bag semantics.
+Records are built from fields that are field-name/field-value pairs, again like JSON.
+(See the [data model document](../datamodel.html) for more details on each.)
-The following examples illustrate how to construct a new ordered list with 3 items, a new record with 2 fields, and a new unordered list with 4 items, respectively. List elements can be homogeneous (as in the first example), which is the common case, or they may be heterogeneous (as in the third example). The data values and field name values used to construct lists and records in constructors are all simply SQL++ expressions. Thus, the list elements, field names, and field values used in constructors can be simple literals or they can come from query variable references or even arbitrarily complex SQL++ expressions (subqueries).
+The following examples illustrate how to construct a new array with 3 items, a new record with 2 fields,
+and a new multiset with 4 items, respectively. Array elements or multiset elements can be homogeneous (as in
+the first example),
+which is the common case, or they may be heterogeneous (as in the third example). The data values and field name values
+used to construct arrays, multisets, and records in constructors are all simply SQL++ expressions. Thus, the collection elements,
+field names, and field values used in constructors can be simple literals or they can come from query variable references
+or even arbitrarily complex SQL++ expressions (subqueries).
##### Examples
@@ -137,17 +149,22 @@
Field ::= "." Identifier
Index ::= "[" ( Expression | "?" ) "]"
-Components of complex types in the data model are accessed via path expressions. Path access can be applied to the result of a SQL++ expression that yields an instance of a complex type, e.g., a record or list instance. For records, path access is based on field names. For ordered lists, path access is based on (zero-based) array-style indexing. SQL++ 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 out-of-bound list elements produce the special value `MISSING`.
+Components of complex types in the data model are accessed via path expressions. Path access can be applied to the result
+of a SQL++ expression that yields an instance of a complex type, e.g., a record or array instance. For records,
+path access is based on field names. For arrays, path access is based on (zero-based) array-style indexing.
+SQL++ also supports an "I'm feeling lucky" style index accessor, [?], for selecting an arbitrary element from an array.
+ Attempts to access non-existent fields or out-of-bound array elements produce the special value `MISSING`.
-The following examples illustrate field access for a record, index-based element access for an ordered list, and also a composition thereof.
+The following examples illustrate field access for a record, index-based element access for an array, and also a
+composition thereof.
##### Examples
- ({"name": "MyABCs", "list": [ "a", "b", "c"]}).list
+ ({"name": "MyABCs", "array": [ "a", "b", "c"]}).array
(["a", "b", "c"])[2]
- ({"name": "MyABCs", "list": [ "a", "b", "c"]}).list[2]
+ ({"name": "MyABCs", "array": [ "a", "b", "c"]}).array[2]
### <a id="Operator_expressions">Operator expressions</a>
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 68573e2..f1ebc47 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/3_query.md
@@ -789,8 +789,8 @@
Collection-valued data is perfectly legal in most SQL++ contexts, and its data is schema-less,
so a query processor rarely knows exactly what to expect where and such automatic conversion is often
not desirable. Thus, in the queries above, the use of "[0]" extracts the first (i.e., 0th) element of
-a list-valued query expression's result; this is needed above, even though the result is a list of one
-element, to "de-listify" the list and obtain the desired scalar for the comparison.
+an array-valued query expression's result; this is needed above, even though the result is an array of one
+element, to extract the only element in the singleton array and obtain the desired scalar for the comparison.
## <a id="Let_clauses">LET clauses</a>
Similar to `WITH` clauses, `LET` clauses can be useful when a (complex) expression is used several times within a query, allowing it to be written once to make the query more concise. The next query shows an example.
@@ -850,7 +850,7 @@
not return singleton, single-column relations.
Instead, they may return arbitrary collections.
For example, the following query is a variant of the prior group-by query examples;
-it retrieves a list of up to two "dislike" messages per user.
+it retrieves an array of up to two "dislike" messages per user.
##### Example
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
index 217a670..d236003 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
@@ -108,19 +108,19 @@
TypeSpecification ::= "TYPE" FunctionOrTypeName IfNotExists "AS" RecordTypeDef
FunctionOrTypeName ::= QualifiedName
IfNotExists ::= ( <IF> <NOT> <EXISTS> )?
- TypeExpr ::= RecordTypeDef | TypeReference | OrderedListTypeDef | UnorderedListTypeDef
+ TypeExpr ::= RecordTypeDef | TypeReference | ArrayTypeDef | MultisetTypeDef
RecordTypeDef ::= ( <CLOSED> | <OPEN> )? "{" ( RecordField ( "," RecordField )* )? "}"
RecordField ::= Identifier ":" ( TypeExpr ) ( "?" )?
NestedField ::= Identifier ( "." Identifier )*
IndexField ::= NestedField ( ":" TypeReference )?
TypeReference ::= Identifier
- OrderedListTypeDef ::= "[" ( TypeExpr ) "]"
- UnorderedListTypeDef ::= "{{" ( TypeExpr ) "}}"
+ ArrayTypeDef ::= "[" ( TypeExpr ) "]"
+ MultisetTypeDef ::= "{{" ( TypeExpr ) "}}"
The CREATE TYPE statement is used to create a new named datatype.
This type can then be used to create stored collections or utilized when defining one or more other datatypes.
Much more information about the data model is available in the [data model reference guide](datamodel.html).
-A new type can be a record type, a renaming of another type, an ordered list type, or an unordered list type.
+A new type can be a record type, a renaming of another type, an array type, or a multiset type.
A record type can be defined as being either open or closed.
Instances of a closed record type are not permitted to contain fields other than those specified in the create type statement.
Instances of an open record type may carry additional fields, and open is the default for new types if neither option is specified.
@@ -129,8 +129,8 @@
Since it is defined as (defaulting to) being an open type,
instances will be permitted to contain more than what is specified in the type definition.
The first four fields are essentially traditional typed name/value pairs (much like SQL fields).
-The friendIds field is an unordered list of integers.
-The employment field is an ordered list of instances of another named record type, EmploymentType.
+The friendIds field is a multiset of integers.
+The employment field is an array of instances of another named record type, EmploymentType.
##### Example
@@ -178,7 +178,7 @@
CompactionPolicy ::= Identifier
The CREATE DATASET statement is used to create a new dataset.
-Datasets are named, unordered collections of record type instances;
+Datasets are named, multisets of record type instances;
they are where data lives persistently and are the usual targets for SQL++ queries.
Datasets are typed, and the system ensures that their contents conform to their type definitions.
An Internal dataset (the default kind) is a dataset whose content lives within and is managed by the system.
@@ -285,7 +285,7 @@
a nested field residing within a record-valued user field in the ChirpMessages dataset.
This index can be useful for accelerating exact-match queries, range search queries,
and joins involving the nested screenName field.
-Such nested fields must be singular, i.e., one cannot index through (or on) a list-valued field.
+Such nested fields must be singular, i.e., one cannot index through (or on) an array-valued field.
#### Example