arm/bicep shallowMerge function

Author: mumian

articles/azure-resource-manager/bicep/bicep-functions-object.md

@@ -385,6 +385,47 @@ The output from the preceding example with the default values is:
 | stringLength | Int | 13 |
 | objectLength | Int | 4 |
 
+## shallowMerge
+
+`shallowMerge(inputArray)`
+
+Combines an array of objects, where only the top-level objects are merged. This means that if the objects being merged contain nested objects, those nested object are not deeply merged; instead, they are replaced entirely by the corresponding property from the merging object.
+
+Namespace: [sys](bicep-functions.md#namespaces-for-functions).
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| inputArray |Yes |array |An array of objects. |
+
+### Return value
+
+An object.
+
+### Example
+
+The following example shows how to use `shallowMerge`:
+
+```bicep
+var firstArray = [{ one: 'a' }, { two: 'b' }, { two: 'c'}]
+var secondArray = [{ one: 'a', nested: {a: 1, nested: {c: 3}} }, { two: 'b', nested: {b: 2}}]
+
+output firstOutput object = shallowMerge(firstArray)
+output secondOutput object = shallowMerge(secondArray)
+```
+
+The output from the preceding example with the default values is:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| firstOutput | object | {"one":"a","two":"c"}|
+| secondOutput | object | {"one":"a","nested":{"b":2},"two":"b"} |
+
+**firstOutput** shows the properties from the merging objects are combined into a new object. If there are conflicting properties (i.e., properties with the same name), the property from the last object being merged usually takes precedence.
+
+**secondOutput** shows the shallow merge does not recursively merge these nested objects. Instead, the entire nested object is replaced by the corresponding property from the merging object.
+
 ## union
 
 `union(arg1, arg2, arg3, ...)`

articles/azure-resource-manager/bicep/bicep-functions.md

@@ -119,6 +119,7 @@ The following functions are available for working with objects. All of these fun
 * [items](./bicep-functions-object.md#items)
 * [json](./bicep-functions-object.md#json)
 * [length](./bicep-functions-object.md#length)
+* [shallowMerge](./bicep-functions-object.md#shallowmerge)
 * [union](./bicep-functions-object.md#union)
 
 ## Parameters file functions

articles/azure-resource-manager/templates/template-functions-object.md

@@ -409,6 +409,87 @@ The output from the preceding example is:
 | ---- | ---- | ----- |
 | emptyOutput | Bool | True |
 
+## shallowMerge
+
+`shallowMerge(inputArray)`
+
+Combines an array of objects, where only the top-level objects are merged. This means that if the objects being merged contain nested objects, those nested object are not deeply merged; instead, they are replaced entirely by the corresponding property from the merging object.
+
+In Bicep, use the [shallowMerge](../bicep/bicep-functions-object.md#shallowmerge) function.
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| inputArray |Yes |array |An array of objects. |
+
+### Return value
+
+An object.
+
+### Example
+
+The following example shows how to use `shallowMerge`:
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "variables": {
+    "firstArray": [
+      {
+        "one": "a"
+      },
+      {
+        "two": "b"
+      },
+      {
+        "two": "c"
+      }
+    ],
+    "secondArray": [
+      {
+        "one": "a",
+        "nested": {
+          "a": 1,
+          "nested": {
+            "c": 3
+          }
+        }
+      },
+      {
+        "two": "b",
+        "nested": {
+          "b": 2
+        }
+      }
+    ]
+  },
+  "resources": [],
+  "outputs": {
+    "firstOutput": {
+      "type": "object",
+      "value": "[shallowMerge(variables('firstArray'))]"
+    },
+    "secondOutput": {
+      "type": "object",
+      "value": "[shallowMerge(variables('secondArray'))]"
+    }
+  }
+}
+```
+
+The output from the preceding example with the default values is:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| firstOutput | object | {"one":"a","two":"c"}|
+| secondOutput | object | {"one":"a","nested":{"b":2},"two":"b"} |
+
+**firstOutput** shows the properties from the merging objects are combined into a new object. If there are conflicting properties (i.e., properties with the same name), the property from the last object being merged usually takes precedence.
+
+**secondOutput** shows the shallow merge does not recursively merge these nested objects. Instead, the entire nested object is replaced by the corresponding property from the merging object.
+
 ## union
 
 `union(arg1, arg2, arg3, ...)`

articles/azure-resource-manager/templates/template-functions.md

@@ -177,6 +177,7 @@ Resource Manager provides several functions for working with objects.
 * [json](template-functions-object.md#json)
 * [length](template-functions-object.md#length)
 * [null](template-functions-object.md#null)
+* [shallowMerge](template-functions-object.md#shallowmerge)
 * [union](template-functions-object.md#union)
 
 For Bicep files, use the [object](../bicep/bicep-functions-object.md) functions.