Cell-Path

Literal Syntax Options

The examples on this page use the weather data from Navigating and Accessing Structured Data:

let data = [
    [date                        temps                                   condition      ];
    [2022-02-01T14:30:00+05:00,  [38.24, 38.50, 37.99, 37.98, 39.10],   'sunny'       ],
    [2022-02-02T14:30:00+05:00,  [35.24, 35.94, 34.91, 35.24, 36.65],   'sunny'       ],
    [2022-02-03T14:30:00+05:00,  [35.17, 36.67, 34.42, 35.76, 36.52],   'cloudy'      ],
    [2022-02-04T14:30:00+05:00,  [39.24, 40.94, 39.21, 38.99, 38.80],   'rain'        ]
]

• Relaxed form:

  $data | get condition.2
  # => cloudy

• Leading $. form:

  When assigning a cell path to a variable, the leading $. syntax is required. Without it, condition.2 is treated as the name of an external command:

  let cp: cell-path = condition.2
  # => Error: nu::shell::external_command
  # =>
  # =>   × External command failed
  # =>    ╭─[repl_entry #1:1:21]
  # =>  1 │ let cp: cell-path = condition.2
  # =>    ·                     ─────┬─────
  # =>    ·                          ╰── Command `condition.2` not found
  # =>    ╰────
  # =>   help: `condition.2` is neither a Nushell built-in or a known external command
  
  let cp: cell-path = $.condition.2
  $data | get $cp
  # => cloudy

  This is not required when using cell-path arguments to a custom command.

• Member modifiers:

  A ? after a member makes it optional (a missing value becomes null instead of an error), and a ! makes it case-insensitive:

  {a: 1}.b? | describe
  # => nothing
  {Name: 1}.name!
  # => 1

Additional Language Notes

1. Ordering

   • When accessing a cell in a table using a cell-path, either the row index or the column name can be listed first.

     # Returns the condition of the first day
     $data | get condition.0
     # => sunny
     # Same result - The condition of the first day
     $data | get 0.condition
     # => sunny

• However, when accessing nested data, the ordering of subsequent (nested) rows and columns is important.

  Using the nested weather data from above:

  # Accesses the second day, third temperature
  $data.1.temps.2
  # => 34.91
  # Also accesses the second day, third temperature
  $data.temps.1.2
  # => 34.91
  # Accesses the third day, second temperature
  $data.temps.2.1
  # => 36.67

  Notice that the first row/column can be swapped without changing the meaning, but swapping the position of the two row indices results in a different path.

1. cell-path can be used as a type annotation.

   Example: A pure-Nushell implementation of the versatile get command.

   def my-get [p: cell-path] {
   get $p
   }
   
   # Now call it
   [1 2 3 4] | my-get 2
   # => 3
   # structured data
   {foo: 1, bar: { baz: {quo: 4}}} | my-get bar.baz.quo
   # => 4
   # with the $ prefix
   {foo: 1, bar: { baz: {quo: 4}}} | my-get $.bar.baz.quo
   # => 4
   # Create a var: $p
   let p: cell-path = $.bar.baz.quo
   # works so far
   # let's try for standard get
   {foo: 1, bar: { baz: {quo: 4}}} | get $p
   # => 4
   # Now with my-get
   {foo: 1, bar: { baz: {quo: 4}}} | my-get $p
   # => 4

2. Cell-paths are not restricted to just the literal values demonstrated above. Cell-paths can also be constructed programmatically using the into cell-path command.

   For example, you can construct the cell path in the temp data programmatically with this code which knows that the location desired is for Grand Rapids, Mich., U.S.A.

   let grr = 2 # using IATA codes for variable names
   let cp: cell-path = ([3, temps, $grr] | into cell-path)
   $cp
   # => $.3.temps.2
   # Returns the GRR temperature for the fourth day
   $data | get $cp
   # => 39.21

Common commands that can be used with cell-path

• get
• select
• update/upsert