difference() function

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


This documentation is open source. See a typo? Please, open an issue.

Need help getting up and running? Get Support