Nushell
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
GitHub
Get Nu!
Getting Started
  • The Nushell Book
  • Command Reference
  • Cookbook
  • Language Reference Guide
  • Contributing Guide
Blog
  • English
  • 中文
  • Deutsch
  • Français
  • Español
  • 日本語
  • Português do Brasil
  • Русский язык
GitHub
  • Language Reference Guide
    • Readme
    • Types in the Nu Language
      • Basic Types
        • Any
        • Boolean
        • Integer
        • Float
        • Filesize
        • Duration
        • Datetime
        • Range
        • String
        • Record
        • List
        • Table
        • Closure
        • Nothing
        • Binary
        • Glob
        • Cell-Path
      • Other Data Types

        • Types that cannot be used to declare variables
          • Path
        • Types which are not declarable
          • Error
          • CustomValue
          • Block
      • Type signatures
      • Commands that interact with types
    • Operators
    • Flow control
      • if/else
      • loop
      • while
      • match
      • try/catch
      • break
      • return
      • continue
    • Filters
      • each and par-each
      • Filters to select subsets of data
      • where and filter
      • Understanding the difference between get and select
    • Custom Commands
    • Declarations
    • Variable Scope
    • Strings and Text Formatting
    • Helpers and debugging commands
    • Pipelines
    • MIME Types for Nushell

Cell-Path

Description:An expression that is used to navigated to an inner value in a structured value.
Annotation:cell-path
Literal syntax example:A dot-separated list of row (int) and column (string) IDs. E.g., name.4.5. Optionally, use a leading $. when needed for disambiguation, such as when assigning a cell-path to a variable (see below).
Casts:into cell-path
See also:Navigating and Accessing Structured Data for an in-depth overview.

Literal Syntax Options

  • Relaxed form:

    > $data | get name.5
  • Leading $. form:

    When assigning a cell path to a variable, the leading $. syntax is required:

    > let cp: cell-path = name.5
    # => Error
    > let cp: cell-path = $.name.5
    
    This is not required when using cell-path arguments to a custom command.

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.

      > ls | get name.0
      # Returns the name of the first file
      > ls | get 0.name
      # Same result - The name of the first file
  • However, when accessing nested data, the ordering of subsequent (nested) rows and columns is important.

    Using the nested weather data example:

    # 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)
    $data | get $cp
    # returns just temps for GRR

Common commands that can be used with cell-path

  • get
  • select
  • update/upsert
Edit this page on GitHub
Contributors: NotTheDr01ds, fdncred
Prev
Glob