Working with Records

tip Records are roughly equivalent to the individual rows of a table. You can think of a record as essentially being a “one-row table”. Thus, most commands which operate on a table row also operates on a record. For instance, update can be used with records:
let my_record = {
 name: "Sam"
 age: 30
 }
$my_record | update age { $in + 1 }
# => ╭──────┬─────╮
# => │ name │ Sam │
# => │ age  │ 31  │
# => ╰──────┴─────╯
Note that the my_record variable is immutable. The updated record resulting from the pipeline is printed as seen in the code block. The my_record variable still holds the original value - $my_record.age is still 30.

Creating records

A record is a collection of zero or more key-value pair mappings. It is similar to a JSON object, and can be created using the same syntax:

# Nushell
{ "apples": 543, "bananas": 411, "oranges": 0 }
# => ╭─────────┬─────╮
# => │ apples  │ 543 │
# => │ bananas │ 411 │
# => │ oranges │ 0   │
# => ╰─────────┴─────╯
# JSON
'{ "apples": 543, "bananas": 411, "oranges": 0 }' | from json
# => ╭─────────┬─────╮
# => │ apples  │ 543 │
# => │ bananas │ 411 │
# => │ oranges │ 0   │
# => ╰─────────┴─────╯

In Nushell, the key-value pairs of a record can also be separated using spaces or line-breaks.

tip As records can have many fields, they are, by default, displayed vertically rather than left-to-right. To display a record left-to-right, convert it to a nuon. For example:
  {
    name: "Sam"
    rank: 10
  } | to nuon
  # =>   {name: Sam, rank: 10}

Updating Records

As with lists, you can insert values in records. For example, let’s add some pears:

{ "apples": 543, "bananas": 411, "oranges": 0 }
| insert pears { 21 }
# => ╭─────────┬─────╮
# => │ apples  │ 543 │
# => │ bananas │ 411 │
# => │ oranges │ 0   │
# => │ pears   │ 21  │
# => ╰─────────┴─────╯

You can also update values:

{ "apples": 543, "bananas": 411, "oranges": 0 }
| update oranges { 100 }
# => ╭─────────┬─────╮
# => │ apples  │ 543 │
# => │ bananas │ 411 │
# => │ oranges │ 100 │
# => ╰─────────┴─────╯

To make a copy of a record with new fields, you can either:

Use the merge command:

let first_record = { name: "Sam", rank: 10 }
$first_record | merge { title: "Mayor" }
# =>   ╭───────┬───────╮
# =>   │ name  │ Sam   │
# =>   │ rank  │ 10    │
# =>   │ title │ Mayor │
# =>   ╰───────┴───────╯

Use the spread operator (...) to expand the first record inside a new record:

let first_record = { name: "Sam", rank: 10 }
{
  ...$first_record
  title: "Mayor"
}
# =>   ╭───────┬───────╮
# =>   │ name  │ Sam   │
# =>   │ rank  │ 10    │
# =>   │ title │ Mayor │
# =>   ╰───────┴───────╯

Iterating over a Record

Use the items command to iterate over each pair of key and value:

{ "apples": 543, "bananas": 411, "oranges": 0 } | items {|fruit, count| $"We have ($fruit) ($count)" }
# => ╭───┬─────────────────────╮
# => │ 0 │ We have apples 543  │
# => │ 1 │ We have bananas 411 │
# => │ 2 │ We have oranges 0   │
# => ╰───┴─────────────────────╯

Alternatively, you can transpose the record into a table with columns, and then iterate over rows:

{ "apples": 543, "bananas": 411, "oranges": 0 }
| transpose fruit count
| each {|f| $"We have ($f.count) ($f.fruit)" }
# => ╭───┬─────────────────────╮
# => │ 0 │ We have 543 apples  │
# => │ 1 │ We have 411 bananas │
# => │ 2 │ We have 0 oranges   │
# => ╰───┴─────────────────────╯

Accessing Record Values

See Navigating and Accessing Structured Data for an in-depth explanation of how to access record values (and other structured data).

Other Record Commands

See Working with Tables - Remember, commands that operate on table rows will usually operate the same way on records.

Tips

Intro

get reads one field from a record.

{name: "nu"} | get name

columns lists the field names.

{a: 1, b: 2} | columns

Basic

insert adds a field you can read back.

{a: 1} | insert b 2 | get b

upsert writes a field even when it exists.

{a: 1} | upsert a 5 | get a

Intermediate

Merge two records and count the fields.

{a: 1} | merge {b: 2} | columns | length

Visit each field value.

{a: 1, b: 2} | items {|k, v| $v} | math sum

Advanced

Insert a field, then measure its text.

{a: 1} | insert b 22 | get b | into string | str length

← Working with Lists Working with Strings →