timescaledb-hyperfunctions

1# TimescaleDB Toolkit Hyperfunctions
2 
3Hyperfunctions are SQL aggregates and accessors from the `timescaledb_toolkit` extension for analysis that plain PostgreSQL aggregates handle badly: percentiles that can be re-aggregated, rates over resetting counters, averages over irregular samples, uptime, state durations, and more.
4 
5## Setup
6 
7```sql
8CREATE EXTENSION IF NOT EXISTS timescaledb_toolkit;   -- preinstalled on Tiger Cloud
9SELECT extversion FROM pg_extension WHERE extname = 'timescaledb_toolkit';
10ALTER EXTENSION timescaledb_toolkit UPDATE;           -- after upgrading the package
11```
12 
13**Only use functions from the default schema in persistent objects.** Anything in the `toolkit_experimental` schema can change between releases, and `ALTER EXTENSION ... UPDATE` **drops** views, continuous aggregates, and functions that depend on it. All functions in this skill are stable.
14 
15## The Two-Step Pattern (read this first)
16 
17Nearly every hyperfunction works in two steps:
18 
191. An **aggregate** builds a compact summary (`percentile_agg(val)` → `uddsketch`, `time_weight(...)` → `timeweightsummary`, ...).
202. An **accessor** extracts a result from the summary (`approx_percentile(0.95, summary)`, `average(summary)`, ...).
21 
22```sql
23-- Function-call style
24SELECT approx_percentile(0.95, percentile_agg(latency_ms)) FROM requests;
25 
26-- Arrow style (same result, reads left to right, chains multiple accessors)
27SELECT percentile_agg(latency_ms) -> approx_percentile(0.95) FROM requests;
28```
29…