> For the complete documentation index, see [llms.txt](https://mikefarah.gitbook.io/yq/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mikefarah.gitbook.io/yq/operators/group-by.md).

# Group By

This is used to group items in an array by an expression.

## Group by field

Given a sample.yml file of:

```yaml
- foo: 1
  bar: 10
- foo: 3
  bar: 100
- foo: 1
  bar: 1
```

then

```bash
yq 'group_by(.foo)' sample.yml
```

will output

```yaml
- - foo: 1
    bar: 10
  - foo: 1
    bar: 1
- - foo: 3
    bar: 100
```

## Group by field, with nulls

Given a sample.yml file of:

```yaml
- cat: dog
- foo: 1
  bar: 10
- foo: 3
  bar: 100
- no: foo for you
- foo: 1
  bar: 1
```

then

```bash
yq 'group_by(.foo)' sample.yml
```

will output

```yaml
- - cat: dog
  - no: foo for you
- - foo: 1
    bar: 10
  - foo: 1
    bar: 1
- - foo: 3
    bar: 100
```