TimescaleDB is a PostgreSQL extension that transforms Postgres into a high-performance time-series database optimized for storing, querying, and analyzing timestamped data at scale. Built as a native extension rather than a fork, TimescaleDB maintains full PostgreSQL compatibility while adding automatic time-based partitioning (hypertables), columnar compression (90-95% storage reduction), continuous aggregates for precomputed rollups, and advanced time-series analytics functions. What sets TimescaleDB apart is its hybrid architecture: data remains in standard PostgreSQL tables under the hood, so you retain all Postgres features (ACID transactions, JOINs, indexes, extensions) while gaining automatic chunk management, intelligent query planning, and purpose-built hyperfunctions. The key mental model: hypertables are abstractions over many time-partitioned chunks, and TimescaleDB handles partitioning, compression, retention, and aggregate refresh automatically in the background — you write SQL as usual, and the extension optimizes everything for time-series workloads without application changes.
What This Cheat Sheet Covers
This topic spans 12 focused tables and 83 indexed concepts. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.
Table 1: Hypertable Creation and Configuration
Everything in TimescaleDB starts with the hypertable — a regular Postgres table that the extension transparently partitions into time-based chunks. These functions are how you create one, tune the chunk interval to match your ingest rate, and optionally add a second partitioning dimension for multi-tenant or high-cardinality workloads. Get the chunk interval right here and most downstream performance follows.
| Function | Example | Description |
|---|---|---|
SELECT create_hypertable('metrics', 'time'); | • Converts a standard PostgreSQL table into a hypertable with automatic time-based partitioning into chunks • must be run on an empty table or specify migrate_data => true for existing data | |
SELECT create_hypertable('sensors', 'ts', chunk_time_interval => INTERVAL '1 day'); | • Sets the time range each chunk covers • default is 7 days but should be tuned based on ingest rate and query patterns (1 day for high-volume, 1 month for low-volume). | |
SELECT set_chunk_time_interval('metrics', INTERVAL '3 days'); | • Changes the chunk interval for future chunks only • existing chunks remain unchanged • useful for adapting to changing data volumes | |
SELECT add_dimension('metrics', 'device_id', number_partitions => 4); | • Adds a hash-based space partition on a second column (e.g., device_id, tenant_id) to distribute data across multiple chunks within each time interval • multi-tenant isolation pattern |