Object Functions

OBJECT_ADD()

This function adds new attributes and values to a given object and returns the updated object.

OBJECT_ADD(object, new_attr_key, new_attr_value)

Note that:

  • This function does not perform key substitution.

  • If you add a duplicate attribute (that is, if the key is found), it returns an error or NULL object.

  • If new_attr_key or new_attr_value is MISSING, or if new_attr_key is NULL, it returns the object unmodified.

  • If object is not an object or NULL, it returns a NULL value object.

Example
SELECT OBJECT_ADD(schedule[0], "day_new", 1)
FROM `travel-sample`
WHERE type = "route"
LIMIT 1;

"results" : [
    {
     "$1": {
         "day": 0,
         "day_new": 1,
         "flight": "AF552",
         "utc": "14:41:00"
         }
   }
]

OBJECT_CONCAT()

This function concatenates the input objects and returns a new object. It requires a minimum of two input objects.

OBJECT_CONCAT(expr1, expr2 ...)
Example
SELECT OBJECT_CONCAT({"abc":1},{"def":2},{"fgh":3});
{
    "requestID": "16982e13-2426-424c-ad90-98104e1d50fd",
    "signature":
    { "$1": "object" }
    ,
    "results": [
        {
            "$1": { "abc": 1, "def": 2, "fgh": 3 }
        }
    ],
    "status": "success",
    "metrics":
    { "elapsedTime": "1.362178ms",
      "executionTime": "1.342968ms",
      "resultCount": 1,
      "resultSize": 122 }
}

OBJECT_INNER_PAIRS(expression)

Description

This function returns an array of values or name-value pairs which contain the attribute name and value pairs of the object, in N1QL collation order of the names. Similar to an INNER JOIN operation, this function returns only the documents for which the parent has a relationship with a child. This function is particularly useful when the argument is an array (such as schedule[0]) as it avoids reporting missing entries for the array.

Arguments
expression

Valid strings or arrays.

Return Value

An array of values or name-value pairs in N1QL collation order and only the documents for which the parent has a relationship with a child.

Example 1: Find one of the flights leaving TLV and arriving at CDG.

SELECT OBJECT_INNER_PAIRS(schedule[0])
FROM `travel-sample`
WHERE type = "route"
    AND destinationairport = "CDG"
    AND sourceairport = "TLV"
LIMIT 1;


Results:
[
  {
    "$1": [
      {
        "name": "day",
        "val": 0
      },
      {
        "name": "flight",
        "val": "IZ610"
      },
      {
        "name": "utc",
        "val": "13:59:00"
      }
    ]
  }
]

Starting Couchbase Server version 4.6.0, the results generated by this function use the word "val" for value instead of the N1QL reserved word "value". For example:

"results": [
    { "$1": [ { "name": "key1", "val": "val1" } ]
    }
]

OBJECT_INNER_VALUES(expression)

This function returns an array of values or name-value pairs which contain the attribute values of the object, in N1QL collation order of the corresponding names. Similar to an INNER JOIN operation, this function returns only the documents for which the parent has a relationship with a child. This function is particularly useful when the argument is an array (such as special_flights[*]) as it avoids reporting missing entries for the array. In the example below, one of the elements in the special_flights array does not have a codename and the output of the function contains only two values and does not include the null entry.

Example
SELECT OBJECT_INNER_VALUES(schedule[0].special_flights[*])
FROM `travel-sample`
WHERE type = "route"
    AND destinationairport = "CDG"
    AND sourceairport = "TLV"
LIMIT 1;
{
    "requestID": "9a980c9b-dc1d-4911-8a5f-8f250dbb8ba3",
    "signature": {
            "$1": "array"
        },
    "results" : [
	{
            "$1": [
                [
                    "green",
                    "yellow"
                ],
                [
                    "AI444",
                    "AI333",
                    "AI222"
                ],
                [
                    "4:44:44",
                    "3:33:33",
                    "2:22:22"
                ]
            ]
        }
	],
    "status": "success",
    "metrics": {
            "elapsedTime": "8.29289ms",
            "executionTime": "8.253102ms",
            "resultCount": 1,
            "resultSize": 391
        }
}

OBJECT_LENGTH(expression)

This function returns the number of name-value pairs in the object. You can specify an object or an expression that evaluates to an object.

Example
SELECT OBJECT_LENGTH(`travel-sample`.schedule[0])
FROM `travel-sample`
WHERE type = "route"
LIMIT 1;

"results" : [
    {
        "$1": 3
    }
]

OBJECT_NAMES(expression)

This function returns an array containing the attribute names of the object, in N1QL collation order.

Example
SELECT OBJECT_NAMES(`travel-sample`.schedule[0])
FROM `travel-sample`
WHERE type = "route"
LIMIT 1;

"results" : [
    {
        "$1": [
            "day",
            "flight",
            "utc"
        ]
    }
]

OBJECT_PAIRS(expression)

Alias: OBJECT_OUTER_PAIRS(expression)

This function returns an array of arrays of values which contain the attribute name and value pairs of the object, in N1QL collation order of the names. Similar to an OUTER JOIN, this function returns every parent document, irrespective of whether the document has a child or not. In the example below, one of the elements in the special_flights array does not have a codename and the output of the function contains three values, including the null entry.

Example
SELECT OBJECT_PAIRS(schedule[0].special_flights[*])
FROM `travel-sample`
WHERE type = "route"
    AND destinationairport = "CDG"
    AND sourceairport = "TLV"
LIMIT 1;
{
    "requestID": "60ec6e75-80a1-4e74-a481-a1e87fafa2e5",
    "signature": {
        "$1": "array"
    },
    "results": [
        {
            "$1": [
                {
                    "name": "codename",
                    "val": [
                        "green",
                        null,
                        "yellow"
                    ]
                },
                {
                    "name": "flight",
                    "val": [
                        "AI444",
                        "AI333",
                        "AI222"
                    ]
                },
                {
                    "name": "utc",
                    "val": [
                        "4:44:44",
                        "3:33:33",
                        "2:22:22"
                    ]
                }
            ]
        }
    ],
    "status": "success",
    "metrics": {
        "elapsedTime": "764.323101ms",
        "executionTime": "764.284035ms",
        "resultCount": 1,
        "resultSize": 725
    }
}

Starting Couchbase Server version 4.6.0, the results generated by this function use the word "val" for value instead of the N1QL reserved word "value". For example:

"results": [
    { "$1": [ { "name": "key1", "val": "val1" } ]
    }
]

OBJECT_PUT()

This function adds new or updates existing attributes and values to a given object, and returns the updated object.

OBJECT_PUT(object, attr_key, attr_value)

Note that:

  • If attr_key is found in the object, it replaces the corresponding attribute value by attr_value.

  • If attr_value is MISSING, it deletes the corresponding existing key (if any), like object_remove().

  • If attr_key is MISSING, it returns a MISSING value.

  • If attr_key is not an object, it returns a NULL value.

Example
SELECT OBJECT_PUT(schedule[0], "day", 1)
FROM `travel-sample`
WHERE type = "route"
LIMIT 1;

"results" : [
    {
         "$1": {
         "day": 1,
         "flight": "AF552",
         "utc": "14:41:00"
         }
    }
]

OBJECT_RENAME(input_obj, old_field, new_field)

Description

Renames the field name old_field to new_field in the JSON input object input_obj.

Arguments
input_obj

Any JSON object, or N1QL expression that can evaluate to a JSON object, representing the search object.

old_field

A string, or any valid expression which evaluates to a string, representing the old (original) field name inside the JSON object input_obj.

new_field

A string, or any valid expression which evaluates to a string, representing the new field name to replace old_field inside the JSON object input_obj.

Return Value

The JSON object input_obj with the new field name.

Examples
Changing the metadata field name from "name" to be "new_name"

SELECT object_rename(t, "name", "new_name")
FROM `travel-sample`
WHERE type = "airline"
LIMIT 1;

[
    {
        "$1": {
          "callsign": "MILE-AIR",
          "country": "United States",
          "iata": "Q5",
          "icao": "MLA",
          "id": 10,
          "new_name": "40-Mile Air",
          "type": "airline"
        }
    }
]

OBJECT_REMOVE()

This function removes the specified attribute and corresponding values from the given object.

OBJECT_REMOVE(object, attr_key)

Note that:

  • If the attr_key is MISSING, it returns a MISSING value.

  • If the attr_key is not an object, it returns a NULL value.

Example
SELECT OBJECT_REMOVE(schedule[0], "day")
FROM `travel-sample`
WHERE type = "route"
LIMIT 1;

"results" : [
    {
        "$1": {
            "flight": "AF552",
            "utc": "14:41:00"
            }
    }
]

SELECT OBJECT_REMOVE( {"abc":1,"def":2,"fgh":3},"def");
{
    "requestID": "ddddde59-e648-4ed7-a772-f25e7a522acc",
    "signature":
    { "$1": "object" }
    ,
    "results": [
        {
            "$1": { "abc": 1, "fgh": 3 }
        }
    ],
    "status": "success",
    "metrics":
    { "elapsedTime": "778.603µs",
      "executionTime": "750.448µs",
      "resultCount": 1,
      "resultSize": 96 }
}

OBJECT_REPLACE(input_obj, old_value, new_value)

Description

Replaces all occurrences of the value value_old to value_new in the JSON input object input_obj.

Arguments
input_obj

Any JSON object, or N1QL expression that can evaluate to a JSON object, representing the search object.

old_value

A string, or any valid expression which evaluates to a string, representing the old (original) value name inside the JSON object input_obj.

new_value

A string, or any valid expression which evaluates to a string, representing the new value name to replace old_value inside the JSON object input_obj.

Return Value

The JSON object input_obj with the new value name.

Examples
Changing the metadata field name from "name" to be "new_name"

SELECT object_rename(t, "airline", "airplane")
FROM `travel-sample`
WHERE type = "airline"
LIMIT 1;

[
    {
        "$1": {
          "callsign": "MILE-AIR",
          "country": "United States",
          "iata": "Q5",
          "icao": "MLA",
          "id": 10,
          "new_name": "40-Mile Air",
          "type": "airplane"
        }
    }
]

OBJECT_UNWRAP(expression)

This function enables you to unwrap an object without knowing the name in the name-value pair. It accepts only one argument and if the argument is an object with exactly one name-value pair, this function returns the value in the name-value pair. If the argument is MISSING, it returns MISSING. For all other cases, it returns NULL.

Examples
SELECT OBJECT_UNWRAP( {"name": "value"} );

"results" : [
    {
        "$1": "value"
    }
]

SELECT OBJECT_UNWRAP( {"name": "MISSING" } );

"results" : [
    {
        "$1": "MISSING"
    }
]

SELECT OBJECT_UNWRAP( { "name": "value", "name2": "value2" } );

"results" : [
    {
        "$1": null
    }
]

SELECT OBJECT_UNWRAP("some-string");

"results" : [
    {
        "$1": null
    }
]

OBJECT_VALUES(expression)

Alias: OBJECT_OUTER_VALUES(expression)

This function returns an array of arrays of values which contain the attribute values of the object, in N1QL collation order of the corresponding names. Similar to an OUTER JOIN, this function returns every parent document, irrespective of whether the document has a child or not. In the example below, one of the elements in the special_flights array does not have a codename and the output of the function contains three values, including the null entry.

Example
SELECT OBJECT_VALUES(schedule[0].special_flights[*])
FROM `travel-sample`
WHERE type = "route"
    AND destinationairport = "CDG"
    AND sourceairport = "TLV"
LIMIT 1;
{
    "requestID": "1d3b3170-690c-4603-b9b5-ab01062fb19a",
    "signature": {
            "$1": "array"
        },
    "results" : [
	{
            "$1": [
                [
                    "green",
                    null,
                    "yellow"
                ],
                [
                    "AI444",
                    "AI333",
                    "AI222"
                ],
                [
                    "4:44:44",
                    "3:33:33",
                    "2:22:22"
                ]
            ]
        }
	],
    "status": "success",
    "metrics": {
            "elapsedTime": "9.376327ms",
            "executionTime": "9.33188ms",
            "resultCount": 1,
            "resultSize": 417
        }
}