MERGE_OBJECTS

The function MERGE_OBJECTS combines objects by adding the properties of additional objects to the object that resulted from merging earlier objects.

This function can take input in two forms: either an arbitrary number of objects or an arbitrarily long list of objects. It outputs a single object, with the properties of the given objects combined. These properties are merged by adding the properties of additional objects to the combination of the previous objects; that is, the resulting object of the MERGE_OBJECT function will have every name-value pair that appears within the last object given, even if that requires the value associated with a previously added name-value pair to be overwritten.

Declaration

MERGE_OBJECTS(object_1, object_2,...object_n) -> combined_object

MERGE_OBJECTS(object_list) -> combined_object

Parameters

object_n(type: object)

The nth object to be merged. There is no upper limit on n; MERGE_OBJECTS can combine any number of objects.

object_list (type: list)

A list of objects to merge. There is no upper limit to the number of items that can occupy this list; MERGE_OBJECTS can combine any number of objects.

Return Values

combined_object (type: object)

The object created by combining the properties of all the given objects, whether they were given as individual objects or in a list of objects. If any of the input objects share property names, the name-value pair in the combined_object will have the same value as the last given object with that property name.

Examples

The following example merges the objects {"first_name": "John"} and {"last_name": "Smith"} into a single object containing both the name-value pair in the first object and the name-value pair in the second object:

MERGE_OBJECTS({"first_name": "John"}, {"last_name": "Smith"}) -> 
{  
 "first_name": "John",  
 "last_name": "Smith"  
}

If the input objects contain only unique property names, such as in the above example, the resulting object contains every name-value pair from within every input object. However, if the input objects share property names, the value given by later objects will overwrite the values given by earlier objects. The following example merges the objects {"first_name": "John"} and {"first_name": "Suzy"} into a single object. Note that the resulting object has "Suzy" as the value of "first_name", because the object {"first_name": "Suzy"} was given after the object {"first_name": "John"}:

MERGE_OBJECTS({"first_name": "John"}, {"first_name": "Suzy"}) -> 
{  
 "first_name": "Suzy"  
}

Switching the order that these input values are given changes which value overwrites the other. The following example merges the objects {"first_name": "Suzy"} and {"first_name": "John"} into a single object. Note that the resulting object has "John" as the value of "first_name", because the object {"first_name": "John"} was given after the object {"first_name": "Suzy"}:

MERGE_OBJECTS({"first_name": "Suzy"}, {"first_name": "John"}) -> 
{  
 "first_name": "John"  
}

MERGE_OBJECTS can be used to combine objects with any number of name-value pairs, and these objects do not need to be hardcoded. Assume the following examples have access to the following variables:

object1 = {  
 "first_name": "Alice",  
 "number": 1,  
 "apples": TRUE  
}  
object2 = {  
"first_name": "Bob",  
"number": 2,  
"bananas": FALSE  
}  
object3 = {  
"first_name": "Carol",  
"number": "three",  
"cucumbers": TRUE  
}

The following example merges the object1 and object2 into a single object. Note that the resulting object has "Bob" as the value of "first_name" and 1 as the value of "number", because the object2 was given after object1:

MERGE_OBJECTS(object1, object2) -> {  
 "first_name": "Bob",   
 "number": 2,   
 "apples": TRUE,   
 "bananas": FALSE  
}

When objects share a property name and one value overwrites another, it makes no difference if these values are not the same type. The above example merged object1 and object2, both of which stored number values under the name "number." object3 stores a string value under the name "number", and the following example demonstrates how MERGE_OBJECTS combines object1, object2, and object3. Note that, because object3 was given last, the value associated with "number" is "three" – there is no indication that object1 and object 2 stored numbers under the same name.

MERGE_OBJECTS(object1, object2, object3) -> 
{  
 "first_name": "Carol",   
 "number": "three",   
 "apples": TRUE,   
 "bananas": FALSE,   
 "cucumbers": TRUE  
}

For the sake of clarity, the above examples took multiple objects as input. However, this does not have to be the case; MERGE_OBJECTS also accepts lists of objects as input. For the next example, assume the formula has access to the following list:

example_list = [object1, object2, object3]

Because example_list lists object1, object2, and object3 in the same order that they were given as input in the above example, using example_list as input in MERGE_OBJECTS results in the same output:

MERGE_OBJECTS(example_list) -> {  
"first_name": "Carol",   
"number": "three",   
"apples": TRUE,   
"bananas": FALSE,   
"cucumbers": TRUE  
}

The MERGE_OBJECTS function can take input in two forms: any number of objects, or a list of objects. It cannot take both at the same time; that is, given a list of objects and another object, it cannot combine all of the given objects the way objects were merged in the above examples. In order for MERGE_OBJECTS to combine the objects given a list with a separate object, MERGE_OBJECTS functions will need to be nested. To demonstrate, assume the last formula has access to the following list:

example_list2 = [object1, object2]

The following example merges the objects in example_list2 – object1 and object2, in that order – and then merges the resulting object with object3. Note that, because the objects were merged in the same order as in the above examples, the output is the same:

MERGE_OBJECTS(MERGE_OBJECTS(example_list2), object3) -> 
{  
"first_name": "Carol",   
"number": "three",   
"apples": TRUE,   
"bananas": FALSE,   
"cucumbers": TRUE  
}