Object Functions

concept

March 23, 2025

+ 12

If you want to try the examples on this page, you must first run the following query to insert additional data to the travel-sample bucket.

Please note that the query below will alter the data in your sample buckets. To restore your sample data, remove and reinstall the travel-sample bucket. Refer to Sample Buckets for details.

n1ql
Copy
UPDATE `travel-sample`.inventory.route
SET schedule[0] = {"day" : 7, "special_flights": [
                    {"flight": "AI444", "utc": "4:44:44", "codename": "green"},
                    {"flight": "AI333", "utc": "3:33:33"},
                    {"flight": "AI222", "utc": "2:22:22", "codename": "yellow"}
                  ] }
WHERE destinationairport = "CDG" AND sourceairport = "TLV";

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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

n1ql
Copy
SELECT OBJECT_ADD(schedule[0], "day_new", 1)
FROM `travel-sample`.inventory.route
LIMIT 1;

Results

json
Copy
[
  {
    "$1": {
      "day": 0,
      "day_new": 1,
      "flight": "AF198",
      "utc": "10:13: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 ...)

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

n1ql
Copy
SELECT OBJECT_CONCAT({"abc":1},{"def":2},{"fgh":3});

Results

json
Copy
{
    "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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

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

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

Results:

json
Copy
[
  {
    "$1": [
      {
        "name": "day",
        "val": 7
      },
      {
        "name": "special_flights",
        "val": [
          {
            "codename": "green",
            "flight": "AI444",
            "utc": "4:44:44"
          },
          {
            "flight": "AI333",
            "utc": "3:33:33"
          },
          {
            "codename": "yellow",
            "flight": "AI222",
            "utc": "2:22:22"
          }
        ]
      }
    ]
  }
]

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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

n1ql
Copy
SELECT OBJECT_INNER_VALUES(schedule[0].special_flights[*])
FROM `travel-sample`.inventory.route
WHERE destinationairport = "CDG"
    AND sourceairport = "TLV"
LIMIT 1;

Results

json
Copy
[
  {
    "$1": [
      [
        "green",
        "yellow"
      ],
      [
        "AI444",
        "AI333",
        "AI222"
      ],
      [
        "4:44:44",
        "3:33:33",
        "2:22:22"
      ]
    ]
  }
]

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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

n1ql
Copy
SELECT OBJECT_LENGTH(R.schedule[0])
FROM `travel-sample`.inventory.route AS R
LIMIT 1;

Results

json
Copy
[
    {
        "$1": 3
    }
]

OBJECT_NAMES(expression)

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

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

n1ql
Copy
SELECT OBJECT_NAMES(R.schedule[0])
FROM `travel-sample`.inventory.route AS R
LIMIT 1;

Results

json
Copy
[
  {
    "$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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

n1ql
Copy
SELECT OBJECT_PAIRS(schedule[0].special_flights[*])
FROM `travel-sample`.inventory.route
WHERE destinationairport = "CDG"
      AND sourceairport = "TLV"
LIMIT 1;

Results

json
Copy
[
  {
    "$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"
        ]
      }
    ]
  }
]

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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

n1ql
Copy
SELECT OBJECT_PUT(schedule[0], "day", 1)
FROM `travel-sample`.inventory.route
LIMIT 1;

Results

json
Copy
[
  {
    "$1": {
      "day": 1,
      "flight": "AF198",
      "utc": "10:13: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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example: Changing the field name from "name" to be "new_name"

n1ql
Copy
SELECT object_rename(t, "name", "new_name")
FROM `travel-sample`.inventory.airline AS t
LIMIT 1;

Results

json
Copy
[
  {
    "$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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

n1ql
Copy
SELECT OBJECT_REMOVE(schedule[0], "day")
FROM `travel-sample`.inventory.route
LIMIT 1;

Results

json
Copy
[
  {
    "$1": {
      "flight": "AF198",
      "utc": "10:13:00"
    }
  }
]

Example

n1ql
Copy
SELECT OBJECT_REMOVE( {"abc":1,"def":2,"fgh":3},"def");

Results

json
Copy
{
    "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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example: Changing the type field value from "airline" to be "airplane"

n1ql
Copy
SELECT object_replace(t, "airline", "airplane")
FROM `travel-sample`.inventory.airline AS t
LIMIT 1;

Results

n1ql
Copy
[
  {
    "$1": {
      "callsign": "MILE-AIR",
      "country": "United States",
      "iata": "Q5",
      "icao": "MLA",
      "id": 10,
      "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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

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.

Make sure that you have run the UPDATE command described in this section before running the example(s).

Example

n1ql
Copy
SELECT OBJECT_VALUES(schedule[0].special_flights[*])
FROM `travel-sample`.inventory.route
WHERE destinationairport = "CDG"
    AND sourceairport = "TLV"
LIMIT 1;

Results

json
Copy
[
  {
    "$1": [
      [
        "green",
        null,
        "yellow"
      ],
      [
        "AI444",
        "AI333",
        "AI222"
      ],
      [
        "4:44:44",
        "3:33:33",
        "2:22:22"
      ]
    ]
  }
]

Object Functions

OBJECT_ADD()

OBJECT_CONCAT()

OBJECT_INNER_PAIRS(expression)

OBJECT_INNER_VALUES(expression)

OBJECT_LENGTH(expression)

OBJECT_NAMES(expression)

OBJECT_PAIRS(expression)

OBJECT_PUT()

OBJECT_RENAME(input_obj, old_field, new_field)

OBJECT_REMOVE()

OBJECT_REPLACE(input_obj, old_value, new_value)

OBJECT_UNWRAP(expression)

OBJECT_VALUES(expression)

OBJECT_INNER_PAIRS(`expression`)