[Book] Unclear example in "Working with Records" for update command

[GrabbenD]

Affected pages:

• https://www.nushell.sh/book/working_with_records.html

Problem:

Following example gives the impression that $my_record should get mutated into 31 (which makes sense when having worked with SQL queries in the past):

let my_record = {
  name: "Sam"
  age: 30
}
$my_record | update age { $in + 1 }
# => ╭──────┬─────╮
# => │ name │ Sam │
# => │ age  │ 31  │
# => ╰──────┴─────╯

However, if you inspect it with print you'll see that wasn't the case:

$ nu script.nu

#!/usr/bin/env nu
let my_record = {
  name: "Sam"
  age: 30
}
$my_record | update age { $in + 1 }
print $my_record # 30

What works

• Assigning the value to a specific variable:

  mut my_record = {
    name: "Sam"
    age: 30
  }
  $my_record = $my_record | update age { $in + 1 }
  print $my_record

• Returning the data from a function:

  def get_record [] {
    let my_record = {
      name: "Sam"
      age: 30
    }
    $my_record | update age { $in + 1 }
  }
  
  let record = (get_record)
  print $record # 31

---

This is merely a unbiased observation from a beginner, please feel free to close this if you don't agree with my assessment 🙂

[fdncred]

I believe that what you've discovered is how it's supposed to work.

$my_record | update age { $in + 1 }

The use of update age ... here isn't supposed to update the variable$my_record. It takes the output of $my_record, updates the output as directed, and reports that output. If you want to store that new output in a variable, you have to tell nushell since variables declared with let are immutable.

Also, when you try to update it like this $my_record = $my_record | update age { $in + 1 }, you're actually not updating the original $my_record, you're shadowing it with a new variable of the same name.

The only mutable variables that nushell has right now is mut variables.

❯ mut a = 5
❯ $a
5
❯ $a = 6
❯ $a
6

https://www.nushell.sh/book/variables.html#types-of-variables

[ysthakur]

I believe this has tripped others up before too. Perhaps we should add in a clarifying comment that update is not meant to mutate the original record, it's meant to create a new updated copy.

[GrabbenD]

That's fair points for sure @fdncred!

After having played around with variables it does make sense but not initially when it's presented at the start of the page, meaning it's confusing for a beginner or someone who touched SQL in the past.

Edit: @ysthakur sniped me