Flux syntax basics

Flux, at its core, is a scripting language designed specifically for working with data. This guide walks through how Flux handles a few simple expressions.

On this page

• Pipe-forward operator
• Simple expressions
• Predicate expressions
• Variables
• Data types
  • Basic types
  • Composite Types
    • Records
    • Arrays
    • Dictionaries
    • Functions
  • Regular expression types
  • View the string representation of any Flux type
• Packages
• Examples of basic syntax
  • Define data stream variables
  • Define custom functions

Pipe-forward operator

The pipe-forward operator (|>) sends the output of one function as input to the next function. In the water treatment metaphor, the pipe-forward operator is the pipe that carries water (or data) through the pipeline.

data
  |> someFunction()
  |> anotherFunction()

Simple expressions

Flux supports basic expressions. For example:

1 + 1
// Returns 2

10 * 3
// Returns 30

(12.0 + 18.0) / (2.0 ^ 2.0) + (240.0 % 55.0)
// Returns 27.5

"John " + "Doe " + "is here!"
// Returns John Doe is here!

For information about operator precedence, see Flux Operators – Operator precedence.

Predicate expressions

A predicate expression compares values using comparison operators, logical operators, or both, and evaluates as true or false. For example:

"John" == "John"
// Returns true

41 < 30
// Returns false

"John" == "John" and 41 < 30
// Returns false

"John" == "John" or 41 < 30
// Returns true

Flux uses predicate expressions when filtering data or in conditional expressions.

Variables

Assign an expression to a variable using the assignment operator (=). Use the name (identifier) of a variable to return its value:

s = "foo" // string
i = 1 // integer
f = 2.0 // float (floating point number)

s // Returns foo
i // Returns 1
f // Returns 2.0

Variables can be assigned to any Flux data type.

Data types

Flux supports many data types grouped into the following categories:

• Basic types
• Composite types
• Regular expression types

Basic types

The following basic types can be represented with literal values:

• Boolean
• Duration
• String
• Time
• Float
• Integer

// Boolean
true

// Duration
23h4m5s

// String
"foo"

// Time
2021-01-01T00:00:00Z

// Float
1.0

// Integer
1

The following basic types do not have a literal syntax, but can be created in other ways:

• Bytes
• Unsigned integers
• Nulls

Composite Types

Flux composite types are constructed from Flux basic types. All composite types have a Flux literal representation.

• Records
• Arrays
• Dictionaries
• Functions

Records

A record is a collections of key-value pairs. Each key is a string. Each value can be a different data type.

{name:"Jim", age: 42, "favorite color": "red"}

Use dot notation or bracket notation to access a properties of a record:

o = {name:"Jim", age: 42, "favorite color": "red"}

o.name
// Returns Jim

o.age
// Returns 42

o["favorite color"]
// Returns red

For more information, see Work with records.

Arrays

An array is a collection of values of the same type.

n = 4
l = [1,2,3,n]

l
// Returns [1, 2, 3, 4]

Use bracket notation to access a value at a specific index in an array:

a = ["foo","bar","baz","quz"]

a[0]
// Returns foo

For more information, see Work with arrays.

Dictionaries

A dictionary is a collection of key-value pairs with keys of the same type and values of the same type.

[1: "foo", 2: "bar"]

Use dict.get() to access elements in a dictionary:

import "dict"

d = [1: "foo", 2: "bar"]

dict.get(dict: d, key: "1", default: "")
// Returns foo

For more information, see Work with dictionaries.

Functions

A function is a block of code that uses a set of parameters to perform an operation. Functions can be named or anonymous. Define parameters in parentheses (()) and pass parameters into an operation with the arrow operator (=>).

square = (n) => n * n

square(n:3)
// Returns 9

Predicate functions

Predicate functions use predicate expressions to evaluate input and return true or false. For example:

examplePredicate = (v) => v == "foo"

examplePredicate(v: "foo")
// Returns true

examplePredicate(v: "bar")
// Returns false

For more information about working with functions, see:

• Work with functions
• Define custom functions

Regular expression types

A regular expression is a regular expression pattern used to evaluate strings. Use regular expressions in predicate expressions or with the regexp package.

regex = /^foo/

"foo" =~ regex
// Returns true

"bar" =~ regex
// Returns false

View the string representation of any Flux type

Use display() to output the Flux literal representation of any value as a string.

x = bytes(v: "foo")

display(v: x)
// Returns "0x666f6f"

Packages

The Flux standard library is organized into packages that contain functions and package-specific options. The universe package is loaded by default. To load other packages, include an import statement for each package at the beginning of your Flux script.

import "array"
import "math"
import "influxdata/influxdb/sample"

Examples of basic syntax

After reading the sections above, you can begin to apply these basic principles in real-world use cases such as creating data stream variables, custom functions, and more.

• Define data stream variables
• Define custom functions

Define data stream variables

A common use case for variable assignments in Flux is creating variables for one or more input data streams. The following example uses sample.data() to query sample air sensor data and assigns different streams of data to unique variables.

import "influxdata/influxdb/sample"

data =
    sample.data(set: "airSensor")
        |> range(start: -15m)
        |> filter(fn: (r) => r._measurement == "airSensors")

temperature =
    data
        |> filter(fn: (r) => r._field == "temperature")

humidity =
    data
        |> filter(fn: (r) => r._field == "humidity")

These variables can be used in other functions, such as join(), while keeping the syntax minimal and flexible.

Define custom functions

Create a function that returns the N number rows with the highest values in the _value column. Pass the input stream (<-) and the number of results to return (n) into a custom function. Use sort() and limit() to find the top n results in the data set.

topN = (tables=<-, n) =>
    tables
        |> sort(desc: true)
        |> limit(n: n)

Use the custom function topN and the humidity data stream variable defined above to return the top three data points in each input table.

humidity
    |> topN(n:3)

For more information about creating custom functions, see Define custom functions.