> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alumio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Group records

> Groups items from a list by the value of a specific key.

export const FormField = ({property, label, required = false, diType, uiPatterns, children}) => {
  const patterns = Array.isArray(uiPatterns) ? uiPatterns : uiPatterns ? [uiPatterns] : [];
  return <div style={{
    margin: '1.5rem 0'
  }}>
      <div style={{
    display: 'flex',
    alignItems: 'baseline',
    flexWrap: 'wrap',
    gap: '0.5rem',
    marginBottom: '0.25rem'
  }}>
        <strong>{label}</strong>
        <span style={{
    fontSize: '0.7rem',
    fontWeight: 600,
    textTransform: 'uppercase',
    letterSpacing: '0.04em',
    color: required ? '#6241f5' : '#6b7280'
  }}>
          {required ? 'Required' : 'Optional'}
        </span>
      </div>

      <div>{children}</div>

      {diType || patterns.length > 0 ? <p style={{
    fontSize: '0.85rem',
    color: '#6b7280',
    marginBottom: 0
  }}>
          {diType ? <>
              See the <a href={`/references/${diType}`}>{diType}</a> reference.{' '}
            </> : null}
          {patterns.length > 0 ? <>
              Accepts a <a href={`/documentation/placeholders-and-patterns/patterns#${patterns[0]}`}>pattern</a>.
            </> : null}
        </p> : null}
    </div>;
};

Sorts a flat list of items into buckets based on a shared value. Use this to take a list of products and group them by category, so all products in the same category end up together. Each item that shares the same value is collected into its own group, and the groups are written to a location you choose. The original list stays in place.

This documentation describes: [Schema](/schemas/transformer/group-by)

## Fields

<FormField property="pattern" label="Source" required uiPatterns="pattern">
  The path to the list of items you want to group. Use `*` to step through every item in the list, for example `products.*`.
</FormField>

<FormField property="path" label="Path" required uiPatterns="path">
  The path inside each item to the value that decides which group it belongs to, for example `category`. Items with the same value here are placed in the same group.
</FormField>

<FormField property="destination" label="Destination" required>
  The path where the grouped result is written, for example `grouped`. The result is an object whose keys are the values found at the grouping path, each holding the list of items that matched. Set this to the same path as the source to replace the original list with the grouped version.
</FormField>

## Sample data

| Field       | Value        |
| ----------- | ------------ |
| Source      | `products.*` |
| Path        | `category`   |
| Destination | `grouped`    |

Input:

```json theme={null}
{
    "products": [
        { "sku": "A1", "category": "shirts" },
        { "sku": "B2", "category": "trousers" },
        { "sku": "C3", "category": "shirts" }
    ]
}
```

Output:

```json theme={null}
{
    "products": [
        { "sku": "A1", "category": "shirts" },
        { "sku": "B2", "category": "trousers" },
        { "sku": "C3", "category": "shirts" }
    ],
    "grouped": {
        "shirts": [
            { "sku": "A1", "category": "shirts" },
            { "sku": "C3", "category": "shirts" }
        ],
        "trousers": [
            { "sku": "B2", "category": "trousers" }
        ]
    }
}
```

```json Configuration theme={null}
{
  "prototype": "group-by",
  "parameters": {
    "pattern": "products.*",
    "path": "category",
    "destination": "grouped"
  }
}
```