TimescaleDB Cheat Sheet
TimescaleDB time-series extension for Postgres covering hypertables, continuous aggregates, compression, and retention policies.
2 PagesIntermediateMar 15, 2026
Creating a Hypertable
Convert a regular Postgres table into a time-partitioned hypertable.
sql
CREATE TABLE metrics ( time TIMESTAMPTZ NOT NULL, device_id TEXT NOT NULL, cpu_pct DOUBLE PRECISION, mem_pct DOUBLE PRECISION);SELECT create_hypertable('metrics', by_range('time'));-- Optional: space-partition by device as wellSELECT add_dimension('metrics', by_hash('device_id', 4));CREATE INDEX ON metrics (device_id, time DESC);
Continuous Aggregate
Incrementally materialized rollups that stay fresh via a background policy.
sql
CREATE MATERIALIZED VIEW metrics_hourlyWITH (timescaledb.continuous) ASSELECT time_bucket('1 hour', time) AS bucket, device_id, avg(cpu_pct) AS avg_cpu, max(cpu_pct) AS max_cpuFROM metricsGROUP BY bucket, device_id;-- Keep it refreshed automaticallySELECT add_continuous_aggregate_policy('metrics_hourly', start_offset => INTERVAL '3 hours', end_offset => INTERVAL '1 hour', schedule_interval => INTERVAL '1 hour');
Compression & Retention Policies
Automatically compress old chunks and drop data past a retention window.
sql
ALTER TABLE metrics SET ( timescaledb.compress, timescaledb.compress_segmentby = 'device_id', timescaledb.compress_orderby = 'time DESC');SELECT add_compression_policy('metrics', INTERVAL '7 days');SELECT add_retention_policy('metrics', INTERVAL '180 days');-- time_bucket_gapfill for dashboards with missing intervalsSELECT time_bucket_gapfill('1 hour', time) AS bucket, device_id, interpolate(avg(cpu_pct))FROM metricsWHERE time > now() - INTERVAL '1 day'GROUP BY bucket, device_id;
Key Functions
TimescaleDB-specific SQL functions you'll use constantly.
- time_bucket(interval, ts)- buckets timestamps into fixed intervals, the core of any rollup query
- create_hypertable()- converts a plain table into an auto-partitioned hypertable
- add_continuous_aggregate_policy()- schedules automatic incremental refresh of a continuous aggregate
- add_compression_policy()- compresses chunks older than a threshold, often 10-20x storage reduction
- show_chunks() / drop_chunks()- inspect or manually drop chunks by age, useful for manual retention control
- locf() / interpolate()- gap-filling functions for dashboards over sparse time-series
Pro Tip
Query continuous aggregates instead of raw hypertables for dashboard panels covering more than a few hours — they're incrementally maintained in the background so reads stay fast even as the underlying hypertable grows into billions of rows.
Was this cheat sheet helpful?
Explore Topics
#TimescaleDB#TimescaleDBCheatSheet#Database#Intermediate#CreatingAHypertable#ContinuousAggregate#CompressionRetentionPolicies#KeyFunctions#Databases#CheatSheet#SkillVeris
Advertisement
Sri Hayavadhana Info-Tech
Professional Web Designing Services
- Responsive Websites
- E-commerce Solutions
- SEO Friendly Design
- Fast & Secure
- Support & Maintenance