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.

Use the influx CLI

Use the influx CLI in “Flux mode” as you follow this guide. When started with -type=flux and -path-prefix=/api/v2/query, the influx CLI is an interactive read-eval-print-loop (REPL) that supports Flux syntax.

Start in the influx CLI in Flux mode

influx -type=flux -path-prefix=/api/v2/query

If using the InfluxData Sandbox, use the ./sandbox enter command to enter the influxdb container, where you can start the influx CLI in Flux mode. You will also need to specify the host as influxdb to connect to InfluxDB over the Docker network.

./sandbox enter influxdb

root@9bfc3c08579c:/# influx -host influxdb -type=flux -path-prefix=/api/v2/query

Basic Flux syntax

The code blocks below provide commands that illustrate the basic syntax of Flux. Run these commands in the influx CLI’s Flux REPL.

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

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.

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"
    )

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

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

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")

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

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

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