# Group By

Group By reshapes one list into groups based on a shared value.

## When to use it

Use it for one digest per manager, one invoice per customer, or any job that needs repeated items kept together. Use [Deduplicate](/documentation/flowcrafter/nodes/flow/deduplicate/) when you want to only keep one item.

## Settings

![Group By settings grouping the Get Entries list by field 2 and retaining items with no value](/documentation/flowcrafter/screenshots/node-group-by-settings.png)

| Setting | What it does |
|---|---|
| **List to group** | Chooses a list from any earlier step. Test the source step first if no list appears. |
| **Group by** | Chooses a field such as `email`, `3`, or `customer.region`. Empty compares whole items. |
| **Give items with no value their own group** | On by default. Off drops items where the chosen field is missing. |

## Output and branches

Group By has one output path and provides:

<table>
  <thead>
    <tr><th style="width: 55%;">Flow tag</th><th>Value</th></tr>
  </thead>
  <tbody>
    <tr><td><code>{{ "Group By".groups }}</code></td><td>The list of groups.</td></tr>
    <tr><td><code>{{ "Group By".group_count }}</code></td><td>The number of groups.</td></tr>
    <tr><td><code>{{ "Group By".count }}</code></td><td>The number of input items, including missing-value items that may be dropped.</td></tr>
  </tbody>
</table>

## Good-to-knows

- Group By does not run a branch per group; connect it to a For Each node to do that.
- In a [For Each](/documentation/flowcrafter/nodes/flow/for-each/) over `groups`, use `{{ item.key }}` for the shared value, `{{ item.count }}` for the group size, and `{{ item.items }}` for its items.
- Group order follows the first appearance of each value.
- Complex object or list keys are returned as hashes, so group by a single value when the key must be readable.
- With [Get Entries](/documentation/flowcrafter/nodes/actions/get-entries/), set **Return** to **Full entries**.

## Example

Group six order entries by customer email. If they belong to three customers, the output has three groups and an input count of `6`. Connect For Each directly and select **Groups** to send one email per customer.

This example connects Group By to **For each customer**. Its **Each item** branch emails `{{ item.key }}` and uses `{{ item.count }}` in the digest; **Done** continues after all groups.

![A Group By example with For Each sending a customer digest on Each item and continuing on Done](/documentation/flowcrafter/screenshots/example-group-by-canvas.png)