groupBy | MuleSoft Documentation
# groupBy
## groupBy<T, R>(items: Array<T>, criteria: (item: T, index: Number) -> R): {| (R): Array<T> |}
Returns an object that groups items from an array based on specified criteria, such as an expression or matching selector.
This version of `groupBy` groups the elements of an array using the `criteria` function. Other versions act on objects and handle null values.
### Parameters
Name | Description  
---|---  
The array to group.  
Expression providing the criteria by which to group the items in the array.  
### Example
This example groups items from the input array `["a","b","c"]` by their indices. Notice that it returns the numeric indices as strings and that items (or values) of the array are returned as arrays, in this case, with a single item each. The items in the array are grouped based on an anonymous function `(item, index) → index` that uses named parameters (`item` and `index`). Note that you can produce the same result using the anonymous parameter `$$` to identify the indices of the array like this: `["a","b","c"] groupBy $$`
#### Source
```
%dw 2.0
output application/json
---
["a","b","c"] groupBy (item, index) -> index
```

#### Output
```
{ "2": [ "c" ], "1": [ "b" ], "0": [ "a" ] }
```

### Example
This example groups the elements of an array based on the language field. Notice that it uses the `item.language` selector to specify the grouping criteria. So the resulting object uses the "language" values (`"Scala"` and `"Java"`) from the input to group the output. Also notice that the output places the each input object in an array.
#### Source
```
%dw 2.0
var myArray = [
  { "name": "Foo", "language": "Java" },
  { "name": "Bar", "language": "Scala" },
  { "name": "FooBar", "language": "Java" }
]
output application/json
---
myArray groupBy (item) -> item.language
```

#### Output
```
{
 "Scala": [
  { "name": "Bar", "language": "Scala" }
 ],
 "Java": [
  { "name": "Foo", "language": "Java" },
  { "name": "FooBar", "language": "Java" }
 ]
}
```

### Example
This example uses `groupBy "myLabels"`to return an object where `"mylabels"` is the key, and an array of selected values (`["Open New", "Zoom In", "Zoom Out", "Original View" ]`) is the value. It uses the selectors (`myVar.menu.items.*label`) to create that array. Notice that the selectors retain all values where `"label"` is the key but filter out values where `"id"` is the key.
#### Source
```
%dw 2.0
var myVar = { menu: {
  header: "Move Items",
  items: [
    {"id": "internal"},
    {"id": "left", "label": "Move Left"},
    {"id": "right", "label": "Move Right"},
    {"id": "up", "label": "Move Up"},
    {"id": "down", "label": "Move Down"}
  ]
}}
output application/json
---
(myVar.menu.items.*label groupBy "myLabels")
```

#### Output
```
{ "myLabels": [ "Move Left", "Move Right", "Move Up", "Move Down" ] }
```

## groupBy<R>(text: String, criteria: (character: String, index: Number) -> R): { (R): String }
Returns an object that groups characters from a string based on specified criteria, such as an expression or matching selector.
This version of `groupBy` groups the elements of an array using the `criteria` function. Other versions act on objects and handle `null` values.
### Parameters
Name | Description  
---|---  
The string to group by.  
The criteria to use.  
### Example
This example shows howyou can use `groupBy` to split a string into vowels and not vowels.
#### Source
```
%dw 2.0
output application/json
---
"hello world!" groupBy (not isEmpty($ find /[aeiou]/))
```

#### Output
```
{
 "false": "hll wrld!",
 "true": "eoo"
}
```

## groupBy<K, V, R>(object: { (K)?: V }, criteria: (value: V, key: K) -> R): { (R): { (K)?: V } }
Groups elements of an object based on criteria that the `groupBy` uses to iterate over elements in the input.
### Parameters
Name | Description  
---|---  
The object containing objects to group.  
The grouping criteria to apply to elements in the input object, such as a `key` and/or `value` of the object to use for grouping.  
### Example
This example groups objects within an array of objects using the anonymous parameter `$` for the value of each key in the input objects. It applies the DataWeave `upper` function to those values. In the output, these values become upper-case keys. Note that you can also write the same example using a named parameter for the within an anonymous function like this: `{ "a" : "b", "c" : "d"} groupBy (value) → upper(value)`
#### Source
```
%dw 2.0
output application/json
---
{ "a" : "b", "c" : "d"} groupBy upper($)
```

#### Output
```
{ "D": { "c": "d" }, "B": { "a": "b" } }
```

### Example
This example uses `groupBy "costs"` to produce a JSON object from an XML object where `"costs"` is the key, and the selected values of the XML element `prices` becomes the JSON value (`{ "price": "9.99", "price": "10.99" }`).
#### Source
```
%dw 2.0
var myRead =
read("<prices><price>9.99</price><price>10.99</price></prices>","application/xml")
output application/json
---
myRead.prices groupBy "costs"
```

#### Output
```
{ "costs" : { "price": "9.99", "price": "10.99" } }
```

## groupBy(value: Null, criteria: (Nothing, Nothing) -> Any): Null
Helper function that enables `groupBy` to work with a `null` value.