Types of Data

Traditional Unix shell commands communicate with each other using strings of text — One command writes text to standard output (often abbreviated stdout) and the other reads text from standard input (or stdin). This allows multiple commands to be combined together to communicate through what is called a “pipeline”.

Nushell embraces this approach and expands it to include other types of data in addition to strings.

Like many programming languages, Nu models data using a set of simple, structured data types. Simple data types include integers, floats, strings, and booleans. There are also special types for dates, file sizes, and time durations.

The describe command returns the type of a data value:

42 | describe
# => int

Types at a Glance

Type	Example
Integers	`-65535`
Floats (decimals)	`9.9999`, `Infinity`
Strings	“hole 18”, ‘hole 18’, `hole 18`, hole18, r#‘hole18’#
Booleans	`true`
Dates	`2000-01-01`
Durations	`2min + 12sec`
File-sizes	`64mb`
Ranges	`0..4`, `0..<5`, `0..`, `..4`
Binary	`0x[FE FF]`
Lists	`[0 1 'two' 3]`
Records	`{name:"Nushell", lang: "Rust"}`
Tables	`[{x:12, y:15}, {x:8, y:9}]`, `[[x, y]; [12, 15], [8, 9]]`
Closures	`{\|e\| $e + 1 \| into string }`, `{ $in.name.0 \| path exists }`
Cell-paths	`$.name.0`
Blocks	`if true { print "hello!" }`, `loop { print "press ctrl-c to exit" }`
Null (Nothing)	`null`
Any	`let p: any = 5`

Basic Data Types

Integers


*Description:*	Numbers without a fractional component (positive, negative, and 0)
*Annotation:*	`int`
*Literal Syntax:*	A decimal, hex, octal, or binary numeric value without a decimal place. E.g., `-100`, `0`, `50`, `+50`, `0xff` (hex), `0o234` (octal), `0b10101` (binary)
*See also:*	Language Reference - Integer

Simple Example:

10 / 2
# => 5
5 | describe
# => int

Floats/Decimals


*Description:*	Numbers with some fractional component
*Annotation:*	`float`
*Literal Syntax:*	A decimal numeric value including a decimal place. E.g., `1.5`, `2.0`, `-15.333`
*See also:*	Language Reference - Float

Simple Example:

2.5 / 5.0
# => 0.5

tip As in most programming languages, decimal values in Nushell are approximate.
10.2 * 5.1
# => 52.01999999999999

Text/Strings


*Description:*	A series of characters that represents text
*Annotation:*	`string`
*Literal Syntax:*	See Working with strings
*See also:*	Handling Strings
	Language Reference - String

As with many languages, Nushell provides multiple ways to specify String values and numerous commands for working with strings.

Simple (obligatory) example:

let audience: string = "World"
$"Hello, ($audience)"
# => Hello, World

Booleans


*Description:*	True or False value
*Annotation:*	`bool`
*Literal Syntax:*	Either a literal `true` or `false`
*See also:*	Language Reference - Boolean

Booleans are commonly the result of a comparison. For example:

let mybool: bool = (2 > 1)
$mybool
# => true
let mybool: bool = ($env.HOME | path exists)
$mybool
# => true

A boolean result is commonly used to control the flow of execution:

let num = -2
if $num < 0 { print "It's negative" }
# => It's negative

Dates


*Description:*	Represents a specific point in time using international standard date-time descriptors
*Annotation:*	`datetime`
*Literal Syntax:*	See Language Guide - Date

Simple example:

date now
# => Mon, 12 Aug 2024 13:59:22 -0400 (now)
# Format as Unix epoch
date now | format date '%s'
# => 1723485562

Durations


*Description:*	Represent a unit of a passage of time
*Annotation:*	`duration`
*Literal Syntax:*	See Language Reference - Duration

Durations support fractional values as well as calculations.

Simple example:

3.14day
# => 3day 3hr 21min
30day / 1sec  # How many seconds in 30 days?
# => 2592000

File sizes


*Description:*	Specialized numeric type to represent the size of files or a number of bytes
*Annotation:*	`filesize`
*Literal Syntax:*	See Language Reference - Filesize

Nushell also has a special type for file sizes.

As with durations, Nushell supports fractional file sizes and calculations:

0.5kB
# => 500 B
1GiB / 1B
# => 1073741824
(1GiB / 1B) == 2 ** 30
# => true

See the Language Reference for a complete list of units and more detail.

Ranges


*Description:*	Describes a range of values from a starting value to an ending value, with an optional stride.
*Annotation:*	`range`
*Literal Syntax:*	`<start_value>..<end_value>`. E.g., `1..10`.
	`<start_value>..<second_value>..<end_value>`. E.g., `2..4..20`
*See also:*	Language Guide - Range

Simple example:

1..5
# => ╭───┬───╮
# => │ 0 │ 1 │
# => │ 1 │ 2 │
# => │ 2 │ 3 │
# => │ 3 │ 4 │
# => │ 4 │ 5 │
# => ╰───┴───╯

tip You can also easily create lists of characters with a form similar to ranges with the command seq char as well as with dates using the seq date command.

Cell Paths


*Description:*	An expression that is used to navigate to an inner value in a structured value.
*Annotation:*	`cell-path`
*Literal syntax:*	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 also:*	Language Reference - Cell-path
	Navigating and Accessing Structured Data chapter.

Simple example:

let cp = $.2
# Return list item at index 2
[ foo bar goo glue ] | get $cp
# => goo

Closures


*Description:*	An anonymous function, often called a lambda function, which accepts parameters and closes over (i.e., uses) variables from outside its scope
*Annotation:*	`closure`
*Literal Syntax:*	`{\|args\| expressions }`
*See also:*	Language Reference - Closure

Simple example:

This closure returns a boolean result of the comparison and then uses it in a where command to return all values greater than 5.

let compare_closure = {|a| $a > 5 }
let original_list = [ 40 -4 0 8 12 16 -16 ]
$original_list | where $compare_closure
# => ╭───┬────╮
# => │ 0 │ 40 │
# => │ 1 │  8 │
# => │ 2 │ 12 │
# => │ 3 │ 16 │
# => ╰───┴────╯

Closures are a useful way to represent code that can be executed on each row of data via filters

Binary data


*Description:*	Represents binary data
*Annotation:*	`binary`
*Literal Syntax:*	`0x[ffffffff]` - hex-based binary representation
	`0o[1234567]` - octal-based binary representation
	`0b[10101010101]` - binary-based binary representation
*See also:*	Language Guide - Binary

Binary data, like the data from an image file, is a group of raw bytes.

Simple example - Confirm that a JPEG file starts with the proper identifier:

open nushell_logo.jpg
| into binary
| first 2
| $in == 0x[ff d8]
# => true

Structured Data Types

Nushell includes a collection of structured data types that can contain the primitive types above. For example, instead of a single float, structured data gives us a way to represent multiple float values, such as a list of temperature readings, in the same value. Nushell supports the following structured data types:

Lists


*Description:*	Ordered sequence of zero or more values of any type
*Annotation:*	`list`
*Literal Syntax:*	See Language Guide - List
*See Also:*	Working with Lists
	Navigating and Accessing Structured Data

Simple example:

[Sam Fred George]
# => ╭───┬────────╮
# => │ 0 │ Sam    │
# => │ 1 │ Fred   │
# => │ 2 │ George │
# => ╰───┴────────╯

Records


*Description:*	Holds key-value pairs which associate string keys with various data values.
*Annotation:*	`record`
*Literal Syntax:*	See Language Guide - Record
*See Also:*	Working with Records
	Navigating and Accessing Structured Data

Simple example:

let my_record = {
  name: "Kylian"
  rank: 99
}
$my_record
# => ╭───────┬────────────╮
# => │ name  │ Kylian     │
# => │ rank  │ 99         │
# => ╰───────┴────────────╯

$my_record | get name
# =>  Kylian

Tables


*Description:*	A two-dimensional container with both columns and rows where each cell can hold any basic or structured data type
*Annotation:*	`table`
*See Also:*	Working with Tables
	Navigating and Accessing Structured Data
	Language Guide - Table

The table is a core data structure in Nushell. As you run commands, you’ll see that many of them return tables as output. A table has both rows and columns.

tip Internally, tables are simply lists of records. This means that any command which extracts or isolates a specific row of a table will produce a record. For example, get 0, when used on a list, extracts the first value. But when used on a table (a list of records), it extracts a record:
[{x:12, y:5}, {x:3, y:6}] | get 0
# => ╭───┬────╮
# => │ x │ 12 │
# => │ y │ 5  │
# => ╰───┴────╯

Other Data Types

Any


*Description:*	When used in a type annotation or signature, matches any type. In other words, a “superset” of other types.
*Annotation:*	`any`
*Literal syntax:*	N/A - Any literal value can be assigned to an `any` type
*See also:*	Language Reference - Any

Blocks


*Description:*	A syntactic form used by some Nushell keywords (e.g., `if` and `for`)
*Annotation:*	N/A
*Literal Syntax:*	N/A
*See also:*	Language Reference - Block

Simple example:

if true { print "It's true" }

The { print "It's true" } portion above is a block.

Nothing (Null)


*Description:*	The `nothing` type is to be used to represent the absence of another value.
*Annotation:*	`nothing`
*Literal Syntax:*	`null`
*See also:*	Language Reference - Nothing

Simple Example

Using the optional operator ? returns null if the requested cell-path doesn’t exist:

let simple_record = { a: 5, b: 10 }
$simple_record.a?
# => 5
$simple_record.c?
# => Nothing is output
$simple_record.c? | describe
# => nothing
$simple_record.c? == null
# => true

Tips

Intro

describe reports the type of a value.

42 | describe

A record is a set of named fields.

{name: "nu"} | describe

Basic

into string changes a number into text.

7 | into string | str length

into int reads digits from text.

"12" | into int | math abs

Intermediate

Convert, measure, and convert back.

99 | into string | str length | into string

Check the type of each list item.

[1 "a"] | each {|n| $n | describe} | length

Advanced

Walk a number through four conversions.

12 | into string | str length | into string | str length

← Special Variables Working with Lists →