docs-v2/content/flux/v0.x/stdlib/universe/stateduration.md

title	description	aliases	menu	weight	flux/v0.x/tags	related	introduced
stateDuration() function	The `stateDuration()` function computes the duration of a given state.	/influxdb/v2.0/reference/flux/functions/transformations/stateduration /influxdb/v2.0/reference/flux/functions/built-in/transformations/stateduration/ /influxdb/v2.0/reference/flux/stdlib/built-in/transformations/stateduration/ /influxdb/cloud/reference/flux/stdlib/built-in/transformations/stateduration/	flux_0_x_ref name parent stateDuration universe	102	transformations	/{{< latest "influxdb" >}}/query-data/flux/monitor-states/ /flux/v0.x/stdlib/contrib/tomhollingworth/events/duration/	0.7.0

stateDuration() returns the cumulative duration of a given state.

The state is defined by the fn predicate function. For each consecutive record that evaluates to true, the state duration is incremented by the duration of time between records using the specified unit. When a record evaluates to false, the value is set to -1 and the state duration is reset. If the record generates an error during evaluation, the point is discarded, and does not affect the state duration.

The state duration is added as an additional column to each record. The duration is represented as an integer in the units specified.

{{% note %}} As the first point in the given state has no previous point, its state duration will be 0. {{% /note %}}

stateDuration(fn: (r) => r._measurement == "state", column: "stateDuration", unit: 1s)

If the expression generates an error during evaluation, the point is discarded, and does not affect the state duration.

Parameters

{{% note %}} Make sure fn parameter names match each specified parameter. To learn why, see Match parameter names. {{% /note %}}

fn

({{< req >}}) A single argument function that evaluates true or false to identify the state of the record. Records are passed to the function. Those that evaluate to true increment the state duration. Those that evaluate to false reset the state duration.

column

Name of the column added to each record that contains the state duration. Default is stateDuration.

unit

Unit of time to increment state duration with. For example: 1s, 1m, 1h, etc. Default is one second (1s).

tables

Input data. Default is piped-forward data (<-).

Examples

{{% flux/sample-example-intro %}}

import "sampledata"

sampledata.int()
    |> stateDuration(fn: (r) => r._value > 10)

{{< expand-wrapper >}} {{% expand "View input and output" %}} {{< flex >}} {{% flex-content %}}

Input data

{{% flux/sample "int" %}}

{{% /flex-content %}} {{% flex-content %}}

Output data

_time	tag	_value	stateDuration
2021-01-01T00:00:00Z	t1	-2	-1
2021-01-01T00:00:10Z	t1	10	-1
2021-01-01T00:00:20Z	t1	7	-1
2021-01-01T00:00:30Z	t1	17	0
2021-01-01T00:00:40Z	t1	15	10
2021-01-01T00:00:50Z	t1	4	-1

_time	tag	_value	stateDuration
2021-01-01T00:00:00Z	t2	19	0
2021-01-01T00:00:10Z	t2	4	-1
2021-01-01T00:00:20Z	t2	-3	-1
2021-01-01T00:00:30Z	t2	19	0
2021-01-01T00:00:40Z	t2	13	10
2021-01-01T00:00:50Z	t2	1	-1
{{% /flex-content %}}
{{< /flex >}}
{{% /expand %}}
{{< /expand-wrapper >}}