yq/pkg/yqlib/doc/operators/sort.md

Sort

Sorts an array. Use sort to sort an array as is, or sort_by(exp) to sort by a particular expression (e.g. subfield).

To sort by descending order, pipe the results through the reverse operator after sorting.

Note that at this stage, yq only sorts scalar fields.

Sort by string field

Given a sample.yml file of:

[{a: banana}, {a: cat}, {a: apple}]

then

yq 'sort_by(.a)' sample.yml

will output

[{a: apple}, {a: banana}, {a: cat}]

Sort by multiple fields

Given a sample.yml file of:

[{a: dog}, {a: cat, b: banana}, {a: cat, b: apple}]

then

yq 'sort_by(.a, .b)' sample.yml

will output

[{a: cat, b: apple}, {a: cat, b: banana}, {a: dog}]

Sort descending by string field

Use sort with reverse to sort in descending order.

Given a sample.yml file of:

[{a: banana}, {a: cat}, {a: apple}]

then

yq 'sort_by(.a) | reverse' sample.yml

will output

[{a: cat}, {a: banana}, {a: apple}]

Sort array in place

Given a sample.yml file of:

cool:
  - a: banana
  - a: cat
  - a: apple

then

yq '.cool |= sort_by(.a)' sample.yml

will output

cool:
  - a: apple
  - a: banana
  - a: cat

Sort array of objects by key

Note that you can give sort_by complex expressions, not just paths

Given a sample.yml file of:

cool:
  - b: banana
  - a: banana
  - c: banana

then

yq '.cool |= sort_by(keys | .[0])' sample.yml

will output

cool:
  - a: banana
  - b: banana
  - c: banana

Sort is stable

Note the order of the elements in unchanged when equal in sorting.

Given a sample.yml file of:

[{a: banana, b: 1}, {a: banana, b: 2}, {a: banana, b: 3}, {a: banana, b: 4}]

then

yq 'sort_by(.a)' sample.yml

will output

[{a: banana, b: 1}, {a: banana, b: 2}, {a: banana, b: 3}, {a: banana, b: 4}]

Sort by numeric field

Given a sample.yml file of:

[{a: 10}, {a: 100}, {a: 1}]

then

yq 'sort_by(.a)' sample.yml

will output

[{a: 1}, {a: 10}, {a: 100}]

Sort by custom date field

Given a sample.yml file of:

[{a: 12-Jun-2011}, {a: 23-Dec-2010}, {a: 10-Aug-2011}]

then

yq 'with_dtf("02-Jan-2006"; sort_by(.a))' sample.yml

will output

[{a: 23-Dec-2010}, {a: 12-Jun-2011}, {a: 10-Aug-2011}]

Sort, nulls come first

Given a sample.yml file of:

[8, 3, null, 6, true, false, cat]

then

yq 'sort' sample.yml

will output

[null, false, true, 3, 6, 8, cat]