Nested Operators and Expressions

In N1QL, nested operators and paths indicate expressions to access nested sub-documents within a JSON document or expression and follow the syntax:

source_expr

Fields:

expression . ( identifier  | escaped identifier [ i ])

Elements:

expression [ expression ]

Array Slicing:

expression [expression : [ expression ] ]

Two special operators are needed to access the data because Couchbase documents containing the data can have nested elements and embedded arrays. The ‘.’ operator is used to refer to children (one level down), and the ‘[ ]’ is used to refer to an element in an array. You can use a combination of these operators to access nested data at any depth in a document.

Field selection

The ‘.’ operator is used to refer to children, that is, one level down in a nested expression.

Nested expressions support using the dot (.) operator to access fields nested inside of other objects. The form .[expression] is used to access an object field named by evaluating the expression contained in the brackets.

field-expression

expression . ( identifier  | escaped identifier [ i ])

By default, field names are case sensitive. To access a field case-insensitively, include the trailing i.

For example, if you have the following data:

{
  "address": {
    "city": "Mountain View"
  },
  "revisions": [2013, 2012, 2011, 2010]
}

The following expressions all evaluate to "Mountain View".

address.city, address.`CITY`i, address.["ci" || "ty"], and address.["CI" || "TY"]i

Element selection

Nested expressions also support using the bracket notation ([position]) to access elements inside an array. The [ ] operator is used to refer to an element in an array. Negative positions are counted backwards from the end of the array.

element-expression

expression [ expression ]

{
    "address": {
    "city": "Mountain View"
    },
    "revisions": [2013, 2012, 2011, 2010]
}}

In our example, the expression revisions[0] evaluates to 2013. The expression revision[-1] evaluates to 2010.

Array slicing

You can get subsets or segments of an array; this is called array slicing. Here is the syntax for array slicing:

source-array [ start_expr : [ end_expr ] ]

It returns a new a subset of the source array, containing the elements from position start to end-1. The element at start is included, while the element at end is not. The array index starts with 0.

If end is omitted, all elements from start to the end of the source array are included.

Negative positions are counted backwards from the end of the array.

The general nested expression has the following syntax.

expression [expression : [ expression ] ]

The following example shows a document and expressions with equivalent values.

{
  "address": {
       "city": "Mountain View"
  },
  "revisions": [2013, 2012, 2011, 2010]
}

The expression address.city evaluates to the value Mountain View.

The expression revisions[0] evaluates to the value 2013.

The expression revisions[1:3] evaluates to the array value [2012, 2011].

The expression revisions[1:] evaluates to the array value [2012, 2011, 2010].