Nested Operators and Expressions

reference

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

A nested expression may contain field selection operators, element selection operators, and array slicing operators.

nested-expr ::= field-expr | element-expr | slice-expr

These special operators are needed to access the data because Couchbase documents can have nested objects and embedded arrays. A field selection operator is used to refer to a field in an object, and an element selection operator 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

Field selection operators use the dot notation . to refer to a child field, that is, a field one level down in a nested object.

Syntax

field-expr ::= expr '.' ( identifier | ( ( escaped-identifier | '[' name-expr ']' ) 'i'? ) )

Arguments

expr: An expression resolving to an object.
identifier
escaped-identifier: An identifier which specifies the name of a field in the object.
name-expr: An expression resolving to a string which specifies the name of a field in the object.

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

Return Value

The value of the specified field.

Example

Given 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.["city"], and address.["CITY"]i

Element Selection

Element selection operators use the bracket notation [ ] to access an element inside a nested array.

Syntax

element-expr ::= expr '[' position ']'

Arguments

expr: An expression resolving to an array.
position: A numeric expression specifying the position of an element in the array, counting from 0. Negative positions are counted backwards from the end of the array.

Return Value

The value of the specified element.

Example

Given the following data:

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

The expression revisions[0] evaluates to 2013. The expression revision[-1] evaluates to 2010.

Array Slicing

The array slicing operator enables you to get subsets or segments of an array.

Syntax

slice-expr ::= expr '[' start-expr ':' end-expr? ']'

Arguments

expr: An expression resolving to an array.
start-expr: 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: [Optional] A numeric expression specifying an end position in the array, counting from 0. Negative positions are counted backwards from the end of the array.

Return Value

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 end position is omitted, all elements from the start position to the end of the source array are included.

Example

Given the following data:

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

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

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