---
schema_version: "1"
id: 481b34836de84548e50c567e6c167e8e7022d3621eaf0fa823e26124ad3ff539
title: groupBy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/dataweave/2.4/dw-core-functions-groupby.md
canonical_url: https://docs.mulesoft.com/dataweave/2.4/dw-core-functions-groupby
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 2276f9abf72f91ef23d894d1cf665b9f97a4a05f513753506e1de8cd7c7da688
description: MuleSoft Documentation Site
release: "2.4"
latest: false
---
---
product: DataWeave
version: 2.4
---

# groupBy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

## 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

<table><colgroup><col> <col></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><p><code>items</code></p></td><td><p>The array to group.</p></td></tr><tr><td><p><code>criteria</code></p></td><td><p>Expression providing the criteria by which to group the items in the array.</p></td></tr></tbody></table>

### 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

```DataWeave
%dw 2.0
output application/json
---
["a","b","c"] groupBy (item, index) -> index
```

#### Output

```JSON
{ "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

```DataWeave
%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

```JSON
{
  "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

```DataWeave
%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

```JSON
{ "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

<table><colgroup><col> <col></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><p><code>text</code></p></td><td><p>The string to group by.</p></td></tr><tr><td><p><code>criteria</code></p></td><td><p>The criteria to use.</p></td></tr></tbody></table>

### Example

This example shows howyou can use `groupBy` to split a string into vowels and not vowels.

#### Source

```DataWeave
%dw 2.0
output application/json
---
"hello world!" groupBy (not isEmpty($ find /[aeiou]/))
```

#### Output

```Json
{
  "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

<table><colgroup><col> <col></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><p><code>object</code></p></td><td><p>The object containing objects to group.</p></td></tr><tr><td><p><code>criteria</code></p></td><td><p>The grouping criteria to apply to elements in the input object, such as a <code>key</code> and/or <code>value</code> of the object to use for grouping.</p></td></tr></tbody></table>

### 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

```DataWeave
%dw 2.0
output application/json
---
{ "a" : "b", "c" : "d"} groupBy upper($)
```

#### Output

```JSON
{ "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

```DataWeave
%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

```JSON
{ "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.