# Item Helper

Sort, limit, deduplicate, group and reshape lists of items.

## Do things in Item Helper

Add an **Item Helper** step and choose an **Operation**. Choose the row to see the fields of each.

- [Transform Items](https://docs.gorunner.io/apps/item-helper#fields-f-transform): Sort · Limit · Deduplicate (Remove Duplicates) · Aggregate (Summarize) · Group By Field · Reverse · Split Out Field (Flatten Array Field) · Count

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Item Helper is `pieceId: "items"` with `actionId: "transform"`, set by `operation`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It computes from its inputs only (`pure`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Item Helper › Transform Items

Sort, limit, deduplicate, aggregate, group, reverse, split out fields, or count items in an array.

### Sort

- **Items · Required**: Array of objects or values to operate on.
- **Field · Optional**: Which value of each item to use, as a dot path (such as user.age). Sort / Deduplicate: optional. Leave blank to compare whole items. Group By / Aggregate: needed when the items are objects. Split Out: the list field to flatten (such as tags).
- **Sort Order · Optional**: Sort smallest-to-largest / A-to-Z (Ascending) or largest-to-smallest / Z-to-A (Descending). Options: Ascending (A→Z / Low→High), Descending (Z→A / High→Low). Default: Ascending (A→Z / Low→High).
- **Sort By Multiple Fields · Optional**: Optional: sort by several fields in priority order. A later field breaks ties on an earlier one. A JSON array like [{"field":"country","order":"asc"},{"field":"age","order":"desc"}]. When set, this overrides the single Field / Sort Order above.

### Limit

- **Items · Required**: Array of objects or values to operate on.
- **Count · Optional**: Maximum number of items to keep. Default: 10.
- **Take From · Optional**: Pick whether to keep the items from the start of the list or from the end. Options: First N items, Last N items. Default: First N items.

### Deduplicate (Remove Duplicates), Group By Field and Split Out Field (Flatten Array Field)

- **Items · Required**: Array of objects or values to operate on.
- **Field · Optional**: Which value of each item to use, as a dot path (such as user.age). Sort / Deduplicate: optional. Leave blank to compare whole items. Group By / Aggregate: needed when the items are objects. Split Out: the list field to flatten (such as tags).

### Aggregate (Summarize)

- **Items · Required**: Array of objects or values to operate on.
- **Field · Optional**: Which value of each item to use, as a dot path (such as user.age). Sort / Deduplicate: optional. Leave blank to compare whole items. Group By / Aggregate: needed when the items are objects. Split Out: the list field to flatten (such as tags).
- **Aggregation · Optional**: How to summarize the chosen field, like adding up numbers (Sum), averaging them, counting items, or joining them into text. Options: Collect (array of field values), Sum (numeric), Average (numeric), Minimum (numeric), Maximum (numeric), Count (number of items), Count Unique (distinct values), Concatenate (join values into text). Default: Collect (array of field values).
- **Separator · Optional**: Text placed between values when concatenating, such as ", ". Default:,. Shows when **Aggregation** is **Concatenate (join values into text)**.

### Reverse and Count

- **Items · Required**: Array of objects or values to operate on.

Source: https://docs.gorunner.io/apps/item-helper