Skip to content
Search ⌘K
Get started

Understand chunks

What chunks are, why they matter for real-time analytics, and how to use them effectively

In Tiger Data products, chunks are the physical partitions behind a hypertable: each one holds rows for a time range (and optional space keys). You always query the hypertable name; the engine routes work to the right chunks. Chunks are what make hypertables fast and manageable. You rarely interact with chunks directly, but understanding them helps you design schemas, tune performance, and reason about how Tiger Cloud (and self-hosted TimescaleDB) organize your data.

For step-by-step tasks (e.g. choosing chunk intervals or listing chunks), see the links in How to use chunks effectively and Learn more.

What are chunks?

Section titled “What are chunks?”

A chunk is a horizontal partition of a hypertable: it is a table that holds rows for a specific time range (and optionally a specific space partition if you use multiple dimensions). When you insert data into a hypertable, TimescaleDB does not store everything in one giant table. Instead, it splits the data into chunks, smaller tables, each responsible for a slice of time (for example one day or one week). That split happens automatically and transparently: you always insert and query against the hypertable name; the system creates and uses chunks behind the scenes.

In practice, a hypertable is the logical table you see; chunks are the physical partitions that store the data. You can think of a hypertable as a single table in SQL, and chunks as the internal “drawers” that the database opens only when they’re needed for a given query or write.

Note

Inheritance is not supported for hypertables (and therefore for chunks). Using table inheritance with hypertables can lead to unexpected behavior.

Why chunks matter

Section titled “Why chunks matter”

Chunks are not just an implementation detail — they are why hypertables can deliver efficient data management, better query performance, and scalable maintenance without you changing how you write SQL.

Query performance and chunk skipping

Section titled “Query performance and chunk skipping”

Time-series queries usually filter by time (for example, “last 24 hours” or “September 2024”). Because each chunk covers a known time range, the query planner can skip chunks that don’t contain any data for that range. So instead of scanning the entire table, TimescaleDB only touches the chunks that might contain matching rows. Chunk skipping dramatically reduces work and speeds up queries. On Tiger Cloud, you can also enable chunk skipping on non-partitioning columns (for example, a “received at” timestamp when the hypertable is partitioned by “event time”), so even more chunks can be skipped when they’re irrelevant to the query.

Maintenance and lifecycle

Section titled “Maintenance and lifecycle”

Many operations in a time-series database are easier when data is partitioned by time:

  • Columnstore: Policies can convert older chunks to columnstore while keeping recent chunks in rowstore for fast inserts and updates. Conversion is applied per chunk.
  • Data retention: You can drop old data by dropping entire chunks (e.g. with drop_chunks()) instead of running row-by-row DELETE, which avoids bloat and is much faster.
  • Tiered storage: On Tiger Cloud, you can move chunks to different storage tiers based on age or access patterns.

So chunks matter because they give the system clear boundaries: “this block of time is hot,” “this block is cold,” “this block can be converted to columnstore or dropped.” That makes automation and tuning predictable.

Parallelism and indexing

Section titled “Parallelism and indexing”

Chunks are independent storage units. The database can process multiple chunks in parallel when executing a query, and indexes are maintained per chunk. That keeps index sizes manageable and allows the planner to use chunk-level statistics. By default, when you create a hypertable, a time-descending index is created; additional indexes you add are also built at the chunk level, which helps both insert and query performance when you have many rows.

How chunks relate to the chunk interval

Section titled “How chunks relate to the chunk interval”

The chunk interval is the time span each chunk is responsible for (e.g. one day or seven days). It is set when you create the hypertable (or later via set_chunk_time_interval()) and determines how many chunks you get for a given time range: smaller intervals mean more, smaller chunks; larger intervals mean fewer, larger chunks.

  • Default: Typically each chunk holds about 7 days of data, but you can change this to match how you ingest and query (e.g. one chunk per day for high-volume, time-bound queries).
  • Creation: When you insert a row whose time falls in a range that doesn’t yet have a chunk, TimescaleDB creates a new chunk for that range automatically. So the number of chunks grows as new time ranges receive data.
  • Columnstore: A columnstore policy often converts chunks to columnar format after a certain age (e.g. after one chunk interval). So the chunk interval also influences when data moves into the columnstore. See the Hypertables and chunks overview for the exact behavior of your version.

Choosing the right chunk interval is a trade-off: you want chunks small enough that active (recent) chunks and their indexes fit in memory for fast access, but not so small that you end up with too many chunks (which can slow query planning and reduce columnstore effectiveness). The Improve hypertable and query performance guide explains how to choose and tune the chunk interval in practice.

How to use chunks effectively

Section titled “How to use chunks effectively”

You don’t need to create or manage chunks manually for normal use — you create a hypertable and insert/query it; chunks are created and used automatically. “Using chunks effectively” means designing and tuning so that chunking works in your favor.

  1. Choose an appropriate chunk interval

    Set the chunk interval when you create the hypertable (or change it for new chunks with set_chunk_time_interval()). A common guideline is to size the interval so that the indexes of chunks you’re currently ingesting into fit within a reasonable share of main memory (e.g. 25% of RAM). For step-by-step guidance and examples, see Optimize hypertable chunk intervals.

  2. Use time-based filters in queries

    Queries that filter on the partitioning (time) column allow the planner to skip irrelevant chunks. If you often filter by another column (e.g. “ingested at”), consider enabling chunk skipping on that column (where supported) so more chunks can be skipped.

  3. Inspect chunks when tuning or debugging

    You can list chunks for a hypertable with show_chunks() and inspect size with functions like chunks_detailed_size(). That’s useful when you’re deciding whether to change the chunk interval or investigating query plans.

  4. Prefer chunk-level operations for bulk lifecycle actions

    For dropping old data, use retention policies or drop_chunks() instead of large DELETEs. For columnstore conversion, policies operate per chunk, so your chunk interval and policy settings work together.

If you’re just getting started, Create and configure a hypertable is the right place to begin; the default chunk interval is a reasonable starting point, and you can refine it later using the guides above.

Learn more

Section titled “Learn more”