# difference() function

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

_time_valuetag
0001nulltv
00026tv
00034tv
000410tv
0005nulltv

#### With nonNegative set to false

``````|> difference(nonNegative: false)
``````
_time_valuetag
0002nulltv
0003-2tv
00046tv
0005nulltv

#### With nonNegative set to true

``````|> difference(nonNegative: true):
``````
_time_valuetag
0002nulltv
0003nulltv
00046tv
0005nulltv

#### With keepFirst set to true

``````|> difference(nonNegative: false, keepFirst: true):
``````
_time_valuetag
0001nulltv
0002nulltv
0003-2tv
00046tv
0005nulltv