Skip to content

chore: update chunk info information. #4224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 26, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions _partials/_chunk-interval.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
$PG builds the index on the fly during ingestion. That means that to build a new entry on the index,
a significant portion of the index needs to be traversed during every row insertion. When the index does not fit
into memory, it is constantly flushed to disk and read back. This wastes IO resources which would otherwise
be used for writing the heap/WAL data to disk.

The default chunk interval is 7 days. However, best practice is to set `chunk_interval` so that prior to processing,
the indexes for chunks currently being ingested into fit within 25% of main memory. For example, on a system with 64
GB of memory, if index growth is approximately 2 GB per day, a 1-week chunk interval is appropriate. If index growth is
around 10 GB per day, use a 1-day interval.

You set `chunk_interval` when you [create a $HYPERTABLE][hypertable-create-table], or by calling
[`set_chunk_time_interval`][chunk_interval] on an existing hypertable.



[best-practices]: /use-timescale/:currentVersion:/hypertables/#best-practices-for-time-partitioning
[chunk_interval]: /api/:currentVersion:/hypertable/set_chunk_time_interval/
[hypertable-create-table]: /api/:currentVersion:/hypertable/create_table/
7 changes: 2 additions & 5 deletions use-timescale/hypertables/improve-query-performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ keywords: [hypertables, indexes, chunks]
---

import OldCreateHypertable from "versionContent/_partials/_old-api-create-hypertable.mdx";
import ChunkInterval from "versionContent/_partials/_chunk-interval.mdx";

# Improve hypertable and query performance

Expand All @@ -27,11 +28,7 @@ Adjusting your hypertable chunk interval can improve performance in your databas

1. **Choose an optimum chunk interval**

The default chunk interval is 7 days. You can set a custom interval when you create a hypertable.
Best practice is that prior to processing, one chunk of data takes up 25% of main memory, including the indexes
from each active hypertable. For example, if you write approximately 2 GB of data per day to a database with 64
GB of memory, set `chunk_interval` to 1 week. If you write approximately 10 GB of data per day on the same
machine, set the time interval to 1 day. For more information, see [best practices for time partitioning][best-practices].
<ChunkInterval />

In the following example you create a table called `conditions` that stores time values in the
`time` column and has chunks that store data for a `chunk_interval` of one day:
Expand Down
9 changes: 4 additions & 5 deletions use-timescale/hypertables/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ keywords: [hypertables]
---

import HypertableIntro from 'versionContent/_partials/_hypertable-intro.mdx';
import ChunkInterval from "versionContent/_partials/_chunk-interval.mdx";

# Hypertables

Expand Down Expand Up @@ -63,11 +64,9 @@ to fit into memory so you can insert and query recent data without
reading from disk. However, having too many small and sparsely filled chunks can
affect query planning time and compression.

Best practice is to set `chunk_interval` so that prior to processing, one chunk of data
takes up 25% of main memory, including the indexes from each active $HYPERTABLE.
For example, if you write approximately 2 GB of data per day to a database with 64 GB of
memory, set `chunk_interval` to 1 week. If you write approximately 10 GB of data per day
on the same machine, set the time interval to 1 day.
<ChunkInterval />



For a detailed analysis of how to optimize your chunk sizes, see the
[blog post on chunk time intervals][blog-chunk-time]. To learn how
Expand Down