Working with Records

Tips

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  │
╰──────┴─────╯

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.

Tips

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

You can iterate over the key-value pairs of a record by first transposing it into a table:

> { "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.