ARM/Bicep groupBy function

Author: mumian

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

@@ -97,6 +97,43 @@ The output from the preceding example:
 
 **filterdLoop** shows the numbers in an array that are greater than 5; and **isEven** shows the even numbers in the array.
 
+## groupBy
+
+`groupBy(inputArray, lambda expression)`
+
+Creates an object with array values from an array, using a grouping condition:
+
+Namespace: [sys](bicep-functions.md#namespaces-for-functions).
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| inputArray |Yes |array |The array for grouping.|
+| lambda expression |Yes |expression |The lambda expression is applied to each input array element, and group the elements using the grouping condition.|
+
+### Return value
+
+An object.
+
+### Examples
+
+The following examples show how to use the `groupBy` function.
+
+```bicep
+var groupObject = groupBy(['foo', 'bar', 'baz'], x => substring(x, 0, 1)) 
+
+output outObject object = groupObject
+```
+
+The output from the preceding example shows the dogs that are five or older:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| outObject | Object | {"f":["foo"],"b":["bar","baz"]} |
+
+**outObject** shows an object that groups the array elements by their first letters.
+
 ## map
 
 `map(inputArray, lambda expression)`

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

@@ -91,6 +91,7 @@ The following functions are available for loading the content from external file
 The following functions are available for working with lambda expressions. All of these functions are in the `sys` namespace.
 
 * [filter](bicep-functions-lambda.md#filter)
+* [groupBy](bicep-functions-lambda.md#groupby)
 * [map](bicep-functions-lambda.md#map)
 * [reduce](bicep-functions-lambda.md#reduce)
 * [sort](bicep-functions-lambda.md#sort)

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

@@ -14,7 +14,6 @@ This article describes the lambda functions to use in ARM templates. [Lambda fun
 lambda(<lambda variable>, [<lambda variable>, ...], <expression>)
 ```
 
-
 > [!TIP]
 > We recommend [Bicep](../bicep/overview.md) because it offers the same capabilities as ARM templates and the syntax is easier to use. To learn more, see [deployment](../bicep/bicep-functions-deployment.md) functions.
 
@@ -139,6 +138,54 @@ The output from the preceding example:
 
 **filterdLoop** shows the numbers in an array that are greater than 5; and **isEven** shows the even numbers in the array.
 
+## groupBy
+
+`groupBy(inputArray, lambda expression)`
+
+Creates an object with array values from an array, using a grouping condition:
+
+In Bicep, use the [groupBy](../bicep/bicep-functions-lambda.md#groupby) function.
+
+### Parameters
+
+| Parameter | Required | Type | Description |
+|:--- |:--- |:--- |:--- |
+| inputArray |Yes |array |The array for grouping.|
+| lambda expression |Yes |expression |The lambda expression is applied to each input array element, and group the elements using the grouping condition.|
+
+### Return value
+
+An object.
+
+### Examples
+
+The following example show how to use the `groupBy` function.
+
+```json
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
+  "contentVersion": "1.0.0.0",
+  "variables": {
+    "groupObject": "[groupBy(createArray('foo', 'bar', 'baz'), lambda('x', substring(lambdaVariables('x'), 0, 1)))]"
+  },
+  "resources": [],
+  "outputs": {
+    "outObject": {
+      "type": "object",
+      "value": "[variables('groupObject')]"
+    }
+  }
+}
+```
+
+The output from the preceding example shows the dogs that are five or older:
+
+| Name | Type | Value |
+| ---- | ---- | ----- |
+| outObject | Object | {"f":["foo"],"b":["bar","baz"]} |
+
+**outObject** shows an object that groups the array elements by their first letters.
+
 ## map
 
 `map(inputArray, lambda function)`