> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-poc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# State aggregation overview

> Track transitions between discrete states with state_agg functions

Track transitions between discrete states for a system or value that switches between them. For example, use `state_agg`
to create a timeline of state transitions, or to calculate the durations of states. `state_agg` extends the capabilities
of [`compact_state_agg`][compact_state_agg].

`state_agg` is designed to work with a relatively small number of states. It might not perform well on datasets where
states are mostly distinct between rows.

Because `state_agg` tracks more information, it uses more memory than `compact_state_agg`. If you want to minimize
memory use and don't need to query the timestamps of state transitions, consider using
[`compact_state_agg`][compact_state_agg] instead.

## Two-step aggregation

This group of functions uses the two-step aggregation pattern.

Rather than calculating the final result in one step, you first create an intermediate aggregate by using the aggregate
function.

Then, use any of the accessors on the intermediate aggregate to calculate a final result. You can also roll up multiple
intermediate aggregates with the rollup functions.

The two-step aggregation pattern has several advantages:

1. More efficient because multiple accessors can reuse the same aggregate
2. Easier to reason about performance, because aggregation is separate from final computation
3. Easier to understand when calculations can be rolled up into larger intervals, especially in window functions and
   [continuous aggregates][caggs]
4. Can perform retrospective analysis even when underlying data is dropped, because the intermediate aggregate stores
   extra information not available in the final result

To learn more, see the [blog post on two-step aggregates][blog-two-step-aggregates].

## Functions in this group

### Aggregate

* [`state_agg()`][state_agg]: aggregate state data into an intermediate form for further computation

### Accessors

* [`state_at()`][state_at]: get the state at a given time
* [`duration_in()`][duration_in]: get the total duration in the specified states
* [`interpolated_duration_in()`][interpolated_duration_in]: get the total duration in the specified states,
  interpolating values at the boundary
* [`state_periods()`][state_periods]: get an array of periods for each state
* [`state_timeline()`][state_timeline]: get a timeline of state changes
* [`interpolated_state_periods()`][interpolated_state_periods]: get an array of periods for each state, interpolating
  values at the boundary
* [`interpolated_state_timeline()`][interpolated_state_timeline]: get a timeline of state changes, interpolating values
  at the boundary
* [`into_values()`][into_values]: return an array of `(state, duration)` pairs from the aggregate

### Rollup

* [`rollup()`][rollup]: combine multiple intermediate aggregates

[blog-two-step-aggregates]: https://www.timescale.com/blog/how-postgresql-aggregation-works-and-how-it-inspired-our-hyperfunctions-design

[caggs]: /manage-data/capabilities/continuous-aggregates

[compact_state_agg]: /api-reference/timescaledb-toolkit/state-tracking/compact_state_agg

[duration_in]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/duration_in

[interpolated_duration_in]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/interpolated_duration_in

[interpolated_state_periods]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/interpolated_state_periods

[interpolated_state_timeline]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/interpolated_state_timeline

[into_values]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/into_values

[rollup]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/rollup

[state_agg]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/state_agg

[state_at]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/state_at

[state_periods]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/state_periods

[state_timeline]: /api-reference/timescaledb-toolkit/state-tracking/state_agg/state_timeline

[toolkit-1.15.0]: https://github.com/timescale/timescaledb-toolkit/releases/tag/1.15.0

[two-step-aggregation]: #two-step-aggregation