difference() function

Warning! This page documents an earlier version of Flux, which is no longer actively developed. Flux v0.65 is the most recent stable version of Flux.

The difference() function computes the difference between subsequent records.
Every user-specified column of numeric type is subtracted while others are kept intact.

Function type: Aggregate
Output data type: Float

difference(nonNegative: false, columns: ["_value"])



Indicates if the difference is allowed to be negative. When set to true, if a value is less than the previous value, it is assumed the previous value should have been a zero.

Data type: Boolean


A list of columns on which to compute the difference. Defaults to ["_value"].

Data type: Array of strings

Subtraction rules for numeric types

  • The difference between two non-null values is their algebraic difference; or null, if the result is negative and nonNegative: true;
  • null minus some value is always null;
  • Some value v minus null is v minus the last non-null value seen before v; or null if v is the first non-null value seen.


from(bucket: "telegraf/autogen")
  |> range(start: -5m)
  |> difference()
from(bucket: "telegraf/autogen")
  |> range(start: -5m)
  |> difference(nonNegative: true)

Example data transformation

Input table
_time A B C tag
0001 null 1 2 tv
0002 6 2 null tv
0003 4 2 4 tv
0004 10 10 2 tv
0005 null null 1 tv

With nonNegative set to false

|> difference(nonNegative: false)
Output table
_time A B C tag
0002 null 1 null tv
0003 -2 0 2 tv
0004 6 8 -2 tv
0005 null null -1 tv

With nonNegative set to true

|> difference(nonNegative: true):
Output table
_time A B C tag
0002 null 1 null tv
0003 null 0 2 tv
0004 6 8 null tv
0005 null null null tv