Object Functions

Object Functions

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",
                    "value": [ "green", null, "yellow" ]
                },
                {
                    "name": "flight",
                    "value": [
                        "AI444",
                        "AI333",
                        "AI222"
                    ]
                },
                {
                    "name": "utc",
                    "value": [
                        "4:44:44",
                        "3:33:33",
                        "2:22:22"
                    ]
                }
            ]
        }
    ],
    "status": "success",
    "metrics": {
        "elapsedTime": "764.323101ms",
        "executionTime": "764.284035ms",
        "resultCount": 1,
        "resultSize": 725
    }
} 

OBJECT_INNER_PAIRS(expression)

This function returns an array 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 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_pairs(schedule[0].special_flights[*])
FROM `travel-sample` 
WHERE type = "route" 
    AND destinationairport = "CDG" 
    AND sourceairport = "TLV" 
LIMIT 1;
{
    "requestID": "719f4ae0-f139-4f2f-a3b2-549451073721",
    "signature": {
        "$1": "array"
    },
    "results": [
        {
            "$1": [
                {
                    "name": "codename",
                    "value": [ "green", "yellow" ]
                },
                {
                    "name": "flight",
                    "value": [
                        "AI444",
                        "AI333",
                        "AI222"
                    ]
                },
                {
                    "name": "utc",
                    "value": [
                        "4:44:44",
                        "3:33:33",
                        "2:22:22"
                    ]
                }
            ]
        }
    ],
    "status": "success",
    "metrics": {
        "elapsedTime": "544.964782ms",
        "executionTime": "544.912708ms",
        "resultCount": 1,
        "resultSize": 695
    }
}

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
        }
}          
      

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_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_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_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"
            }
    }
]         

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
    }
]