Merge pull request #274990 from mumian/0510-function-groupby

ARM/Bicep groupBy function

Author: v-shils

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

@@ -3,7 +3,7 @@ title: Bicep functions - lambda
 description: Describes the lambda functions to use in a Bicep file.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 05/13/2024
+ms.date: 05/21/2024
 ---
 # Lambda functions for Bicep
 
@@ -38,7 +38,7 @@ Namespace: [sys](bicep-functions.md#namespaces-for-functions).
 | Parameter | Required | Type | Description |
 |:--- |:--- |:--- |:--- |
 | inputArray |Yes |array |The array to filter.|
-| lambda expression |Yes |expression |The lambda expression is applied to each input array element. If the result is true, the item will be included in the output array; otherwise, the item is discarded.|
+| lambda expression |Yes |expression |The lambda expression is applied to each input array element. If the result is true, the item is included in the output array; otherwise, the item is discarded.|
 
 ### Return value
 
@@ -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 inputArray = ['foo', 'bar', 'baz']
+
+output outObject object = groupBy(inputArray, x => substring(x, 0, 1)) 
+```
+
+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)
 * [mapValue](bicep-functions-lambda.md#mapvalues)
 * [reduce](bicep-functions-lambda.md#reduce)

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,58 @@ 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 shows 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": {
+    "inputArray": [
+      "foo",
+      "bar",
+      "baz"
+    ]
+  },
+  "resources": [],
+  "outputs": {
+    "outObject": {
+      "type": "object",
+      "value": "[groupBy(variables('inputArray'), lambda('x', substring(lambdaVariables('x'), 0, 1)))]"
+    }
+  }
+}
+```
+
+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)`

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

@@ -141,6 +141,7 @@ For Bicep files, use the [deployment](../bicep/bicep-functions-deployment.md) fu
 Resource Manager provides the following functions for working with lambda expressions.
 
 * [filter](template-functions-lambda.md#filter)
+* [groupBy](template-functions-lambda.md#groupby)
 * [map](template-functions-lambda.md#map)
 * [mapValues](template-functions-lambda.md#mapvalues)
 * [reduce](template-functions-lambda.md#reduce)