docs-v2/content/v2.0/reference/flux/stdlib/built-in/transformations/difference.md

title	description	aliases	menu	weight	aliases	related
difference() function	The `difference()` function computes the difference between subsequent non-null records.	/v2.0/reference/flux/functions/transformations/aggregates/difference /v2.0/reference/flux/functions/built-in/transformations/aggregates/difference/	v2_0_ref name parent difference built-in-transformations	402	/v2.0/reference/flux/stdlib/built-in/transformations/aggregates/difference	https://docs.influxdata.com/influxdb/latest/query_language/functions/#difference, InfluxQL – DIFFERENCE()

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

Function type: Transformation
Output data type: Float

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

Parameters

nonNegative

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

columns

The columns to use to compute the difference. Defaults to ["_value"].

Data type: Array of Strings

keepFirst

Indicates the first row should be kept. If true, the difference will be null. Defaults to false.

Data type: Boolean

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.

Output tables

For each input table with n rows, difference() outputs a table with n - 1 rows.

Examples

from(bucket: "example-bucket")
  |> range(start: -5m)
  |> difference()

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

Example data transformation

Input table

_time	_value	tag
0001	null	tv
0002	6	tv
0003	4	tv
0004	10	tv
0005	null	tv

With nonNegative set to false

|> difference(nonNegative: false)

Output table

_time	_value	tag
0002	null	tv
0003	-2	tv
0004	6	tv
0005	null	tv

With nonNegative set to true

|> difference(nonNegative: true):

Output table

_time	_value	tag
0002	null	tv
0003	null	tv
0004	6	tv
0005	null	tv

With keepFirst set to true

|> difference(nonNegative: false, keepfirst: true):

Output table

_time	_value	tag
0001	null	tv
0002	null	tv
0003	-2	tv
0004	6	tv
0005	null	tv