Documentation

Flux syntax basics

Flux, at its core, is a scripting language designed specifically for working with data. This guide walks through a handful of simple expressions and how they are handled in Flux.

Simple expressions

Flux is a scripting language that supports basic expressions. For example, simple addition:

> 1 + 1
2

Variables

Assign an expression to a variable using the assignment operator, =.

> s = "this is a string"
> i = 1 // an integer
> f = 2.0 // a floating point number

Type the name of a variable to print its value:

> s
this is a string
> i
1
> f
2

Records

Flux also supports records. Each value in a record can be a different data type.

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

Use dot notation to access a properties of a record:

> o.name
Jim
> o.age
42

Or bracket notation:

> o["name"]
Jim
> o["age"]
42
> o["favorite color"]
red

Use bracket notation to reference record properties with special or white space characters in the property key.

Lists

Flux supports lists. List values must be the same type.

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

Functions

Flux uses functions for most of its heavy lifting. Below is a simple function that squares a number, n.

> square = (n) => n * n
> square(n:3)
9

Flux does not support positional arguments or parameters. Parameters must always be named when calling a function.

Pipe-forward operator

Flux uses the pipe-forward operator (|>) extensively to chain operations together. After each function or operation, Flux returns a table or collection of tables containing data. The pipe-forward operator pipes those tables into the next function where they are further processed or manipulated.

data |> someFunction() |> anotherFunction()

Real-world application of basic syntax

This likely seems familiar if you’ve already been through through the other getting started guides. Flux’s syntax is inspired by Javascript and other functional scripting languages. As you begin to apply these basic principles in real-world use cases such as creating data stream variables, custom functions, etc., the power of Flux and its ability to query and process data will become apparent.

The examples below provide both multi-line and single-line versions of each input command. Carriage returns in Flux aren’t necessary, but do help with readability. Both single- and multi-line commands can be copied and pasted into the influx CLI running in Flux mode.

Define data stream variables

A common use case for variable assignments in Flux is creating variables for one or more input data streams.

timeRange = -1h

cpuUsageUser = from(bucket: "telegraf/autogen")
    |> range(start: timeRange)
    |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user" and r.cpu == "cpu-total")

memUsagePercent = from(bucket: "telegraf/autogen")
    |> range(start: timeRange)
    |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent")

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 in the input stream with the highest _values. To do this, pass the input stream (tables) and the number of results to return (n) into a custom function. Then using Flux’s sort() and limit() functions to find the top n results in the data set.

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

More information about creating custom functions is available in the Custom functions documentation.

Using this new custom function topN and the cpuUsageUser data stream variable defined above, find the top five data points and yield the results.

cpuUsageUser
    |> topN(n: 5)
    |> yield()

Define data stream variables

A common use case for variable assignments in Flux is creating variables for multiple filtered input data streams.

timeRange = -1h

cpuUsageUser = from(bucket: "telegraf/autogen")
    |> range(start: timeRange)
    |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user" and r.cpu == "cpu-total")

memUsagePercent = from(bucket: "telegraf/autogen")
    |> range(start: timeRange)
    |> filter(fn: (r) => r._measurement == "mem" and r._field == "used_percent")

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

Define custom functions

Let’s create a function that returns the N number rows in the input data stream with the highest _values. To do this, pass the input stream (tables) and the number of results to return (n) into a custom function. Then using Flux’s sort() and limit() functions to find the top n results in the data set.

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

More information about creating custom functions is available in the Custom functions documentation.

Using the cpuUsageUser data stream variable defined above, find the top five data points with the custom topN function and yield the results.

cpuUsageUser |> topN(n:5) |> yield()

This query will return the five data points with the highest user CPU usage over the last hour.


Was this page helpful?

Thank you for your feedback!


Set your InfluxDB URL

Linux Package Signing Key Rotation

All signed InfluxData Linux packages have been resigned with an updated key. If using Linux, you may need to update your package configuration to continue to download and verify InfluxData software packages.

For more information, see the Linux Package Signing Key Rotation blog post.

InfluxDB Cloud backed by InfluxDB IOx

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by IOx, this is the correct documentation.

If powered by TSM, see the TSM-based InfluxDB Cloud documentation.

InfluxDB Cloud backed by InfluxDB TSM

All InfluxDB Cloud organizations created on or after January 31, 2023 are backed by the new InfluxDB IOx storage engine which enables nearly unlimited series cardinality and SQL query support. Check the right column of your InfluxDB Cloud organization homepage to see which InfluxDB storage engine you’re using.

If powered by TSM, this is the correct documentation.

If powered by IOx, see the IOx-based InfluxDB Cloud documentation.

State of the InfluxDB Cloud (IOx) documentation

The new documentation for InfluxDB Cloud backed by InfluxDB IOx is a work in progress. We are adding new information and content almost daily. Thank you for your patience!

If there is specific information you’re looking for, please submit a documentation issue.