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
- Packages
- Examples of basic syntax
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
The following basic types can be represented with literal values:
// 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:
Composite Types
Flux composite types are constructed from Flux basic types. All composite types have a Flux literal representation.
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:
Use bracket notation to reference record properties with special or white space characters in the property key.
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
Flux does not support positional parameters. Parameters must always be named when calling a function.
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:
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
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.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for Flux and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.