filters

Merge the input with a record or table, recursively merging values in matching columns.

Signature

> merge deep {flags} (value)

Flags

• --strategy, -s {string}: The list merging strategy to use. One of: table (default), overwrite, append, prepend

Parameters

• value: The new value to merge with.

Input/output types:

input	output
record	record
table	table

Examples

Merge two records recursively

> {a: 1, b: {c: 2, d: 3}} | merge deep {b: {d: 4, e: 5}}
╭───┬───────────╮
│ a │ 1         │
│   │ ╭───┬───╮ │
│ b │ │ c │ 2 │ │
│   │ │ d │ 4 │ │
│   │ │ e │ 5 │ │
│   │ ╰───┴───╯ │
╰───┴───────────╯

Merge two tables

> [{columnA: 0, columnB: [{B1: 1}]}] | merge deep [{columnB: [{B2: 2}]}]
╭───┬─────────┬─────────────────╮
│ # │ columnA │     columnB     │
├───┼─────────┼─────────────────┤
│ 0 │       0 │ ╭───┬────┬────╮ │
│   │         │ │ # │ B1 │ B2 │ │
│   │         │ ├───┼────┼────┤ │
│   │         │ │ 0 │  1 │  2 │ │
│   │         │ ╰───┴────┴────╯ │
╰───┴─────────┴─────────────────╯

Merge two records and their inner tables

> {inner: [{a: 1}, {b: 2}]} | merge deep {inner: [{c: 3}]}
╭───────┬──────────────────────╮
│       │ ╭───┬────┬────┬────╮ │
│ inner │ │ # │ a  │ c  │ b  │ │
│       │ ├───┼────┼────┼────┤ │
│       │ │ 0 │  1 │  3 │ ❎ │ │
│       │ │ 1 │ ❎ │ ❎ │  2 │ │
│       │ ╰───┴────┴────┴────╯ │
╰───────┴──────────────────────╯

Merge two records, appending their inner tables

> {inner: [{a: 1}, {b: 2}]} | merge deep {inner: [{c: 3}]} --strategy=append
╭───────┬──────────────────────╮
│       │ ╭───┬────┬────┬────╮ │
│ inner │ │ # │ a  │ b  │ c  │ │
│       │ ├───┼────┼────┼────┤ │
│       │ │ 0 │  1 │ ❎ │ ❎ │ │
│       │ │ 1 │ ❎ │  2 │ ❎ │ │
│       │ │ 2 │ ❎ │ ❎ │  3 │ │
│       │ ╰───┴────┴────┴────╯ │
╰───────┴──────────────────────╯

Notes

The way that key-value pairs which exist in both the input and the argument are merged depends on their types.

Scalar values (like numbers and strings) in the input are overwritten by the corresponding value from the argument. Records in the input are merged similarly to the merge command, but recursing rather than overwriting inner records.

The way lists and tables are merged is controlled by the --strategy flag:

• table: Merges tables element-wise, similarly to the merge command. Non-table lists are overwritten.
• overwrite: Lists and tables are overwritten with their corresponding value from the argument, similarly to scalars.
• append: Lists and tables in the input are appended with the corresponding list from the argument.
• prepend: Lists and tables in the input are prepended with the corresponding list from the argument.