[DOC-10552] Changes to array operators and functions (#371)

Author: rakhi-prathap

modules/n1ql/assets/images/n1ql-language-reference/slice-expr.png

@@ -1497,6 +1497,119 @@ SELECT array_star(children).age FROM contacts WHERE fname = "Dave"
 ----
 ====
 
+=== Empty Array Subscripts
+
+You can use an empty array subscript (`[ ]`) to return an array that includes only defined elements. 
+
+The rules governing its use are as follows: 
+
+[cols="1a,2a"]
+|====
+| Expression | Description 
+
+| `field[]` 
+|* If `field` is not an array, it returns `NULL`.  
+* If `field` is an array, it returns the array as is.
+
+
+| `field[][]`
+|* If `field` is not an array, it returns `NULL`.
+* If `field` contains only unnamed arrays, it returns `field` as is.
+Otherwise, it returns `NULL`.
+
+| `field[].field2`
+|* If `field` is not an array, it returns `MISSING`.
+* If `field` is an array, it extracts `field2` from each element in `field` and returns a new array with those values.
+* If `field` contains unnamed arrays, they are flattened by one level. 
+Then from the resulting array, it extracts `field2` from each object where it is present.
+
+| `field[][].field2`
+|* If `field` is not an array, it returns `MISSING`.
+* If every element in `field` is not an unnamed array, it returns `MISSING`.
+* If `field` contains unnamed arrays, they are flattened by one level.
+Then from the resulting array, it extracts `field2` from each object where it is present.
+
+
+| `field[].field2[].field3`
+|* Returns an array of `field3` values by traversing two levels of arrays.
+First it extracts `field2` from each element of `field`, then extracts `field3` from each element of the resulting `field2` array.
+* If `field` and `field2` contain unnamed arrays, they are flattened by one level.
+Then from the resulting `field2` array, it extracts `field3` from each object where it is present.
+
+|====
+
+NOTE: If you use more that two empty array subscripts (for example, `field[][][]`), the function considers only the first two subscripts and ignores the rest.
+
+==== Example
+
+====
+Given the following sample document:
+
+[source,json]
+----
+{
+  "a": {
+    "airline": "AF",
+    "airlineid": "airline_003",
+    "destinationairport": "SFO",
+    "distance": 2481.617376098415,
+    "equipment": "320",
+    "id": 3,
+    "schedule": [
+      {
+        "day": 0,
+        "flight": "AF198",
+        "utc": "10:13:00"
+      },
+      {
+        "flight": "AF250",
+        "utc": "12:59:00"
+      },
+      {
+        "day": 2,
+        "flight": "AF223",
+        "special_flights": [
+          {
+            "a": "SA"
+          },
+          {
+            "b": [
+              [
+                {
+                  "c": "SC1"
+                },
+                {
+                  "c": "SC2"
+                }
+              ],
+              [
+                {
+                  "c": "SC3"
+                }
+              ]
+            ]
+          }
+        ],
+        "utc": "19:41:00"
+      }
+    ],
+    "sourceairport": "DFW"
+  }
+}
+----
+
+Here's how different array subscripts evaluate:
+
+* `a.airline[]`: Returns `NULL` (not an array).
+* `a.schedule[]`: Equivalent to `a.schedule`, returns the array.
+* `a.schedule[].day`: Returns `[0, 2]`. This is in contrast to `a.schedule[*].day`, which returns `[0, null, 2]`.
+* `a.schedule[].special_flights[].a`: Returns `["SA"]`.
+* `a.schedule[][].utc`: Returns `MISSING`.
+* `a.schedule[].special_flights[].b[][].c`: Returns `["SC1", "SC2", "SC3"]`.
+* `a.schedule[].special_flights[].b[].c`: Also returns `["SC1", "SC2", "SC3"]`, as the unnamed arrays are flattened. 
+
+====
+
 [[fn-array-sum,ARRAY_SUM()]]
 == ARRAY_SUM([.var]`expr`)
 

modules/n1ql/pages/n1ql-language-reference/arrayfun.adoc

@@ -132,7 +132,7 @@ expr::
 An expression resolving to an array.
 
 start-expr::
-A numeric expression specifying a start position in the array, counting from 0.
+[Optional] A numeric expression specifying a start position in the array, counting from 0.
 Negative positions are counted backwards from the end of the array.
 
 end-expr::
@@ -144,6 +144,8 @@ Negative positions are counted backwards from the end of the array.
 A new subset of the source array, containing the elements from the start position to the end position minus 1.
 The element at the start position is included, while the element at the end position is not.
 
+If the start position is omitted, the subset starts from the beginning of the source array. 
+
 If the end position is omitted, all elements from the start position to the end of the source array are included.
 
 === Example
@@ -164,4 +166,6 @@ Given the following data:
 The expression `revisions[1:3]` evaluates to the array value `[2012, 2011]`.
 
 The expression `revisions[1:]` evaluates to the array value `[2012, 2011, 2010]`.
+
+The expression `revisions[:2]` evaluates to the array value `[2013, 2012]`.
 ====

modules/n1ql/pages/n1ql-language-reference/nestedops.adoc

@@ -260,7 +260,7 @@ element-expr ::= expr '[' position ']'
 /* end::element-expr[] */
 
 /* tag::slice-expr[] */
-slice-expr ::= expr '[' start-expr ':' end-expr? ']'
+slice-expr ::= expr '[' start-expr? ':' end-expr? ']'
 /* end::slice-expr[] */
 
 start-expr ::= expr