From f628b5ffb1b5c45a66725c680f1528453f8ef9ec Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 9 Oct 2025 10:49:30 +0200 Subject: [PATCH 1/3] chore: remove best practice sentence from dimension partitioning section. --- use-timescale/hypertables/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/use-timescale/hypertables/index.md b/use-timescale/hypertables/index.md index 36569946dd..c3d289fdbe 100644 --- a/use-timescale/hypertables/index.md +++ b/use-timescale/hypertables/index.md @@ -41,8 +41,6 @@ the number of chunks you see when inspecting it. Partitioning on time is the most common use case for $HYPERTABLE, but it may not be enough for your needs. For example, you may need to scan for the latest readings that match a certain condition without locking a critical $HYPERTABLE. -Best practice to optimize ingest and query performance is to add a partitioning dimension on a non-time column such as -location or device UUID, and specify a number of partitions. You add a partitioning dimension at the same time as you create the hypertable, when the table is empty. The good news is that although you select the number of partitions at creation time, as your data grows you can change the number of From 7adf041dbbf9da32d1fc0c2493b30f75715f3912 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 9 Oct 2025 14:38:00 +0200 Subject: [PATCH 2/3] chore: add scary note. --- use-timescale/hypertables/index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/use-timescale/hypertables/index.md b/use-timescale/hypertables/index.md index c3d289fdbe..a6363677d0 100644 --- a/use-timescale/hypertables/index.md +++ b/use-timescale/hypertables/index.md @@ -42,6 +42,14 @@ the number of chunks you see when inspecting it. Partitioning on time is the most common use case for $HYPERTABLE, but it may not be enough for your needs. For example, you may need to scan for the latest readings that match a certain condition without locking a critical $HYPERTABLE. + + +The use case for a partitioning dimension is a multi-tenant setup. You isolate the tenants using the `tenant_id` space +partition. However, you must perform extensive testing to ensure this works as expected, and there is a strong risk of +partition explosion, + + + You add a partitioning dimension at the same time as you create the hypertable, when the table is empty. The good news is that although you select the number of partitions at creation time, as your data grows you can change the number of partitions later and improve query performance. Changing the number of partitions only affects chunks created after the From a137559aaf86184c7d4564e282d97e1be5ea13a4 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 9 Oct 2025 15:03:48 +0200 Subject: [PATCH 3/3] chore: add scary note. --- use-timescale/hypertables/index.md | 84 ++++++++++++++---------------- 1 file changed, 39 insertions(+), 45 deletions(-) diff --git a/use-timescale/hypertables/index.md b/use-timescale/hypertables/index.md index a6363677d0..306d5d3ae2 100644 --- a/use-timescale/hypertables/index.md +++ b/use-timescale/hypertables/index.md @@ -37,6 +37,38 @@ might be a time gap between the start time and the earliest timestamp. This doesn't affect your usual interactions with your $HYPERTABLE, but might affect the number of chunks you see when inspecting it. +## Best practices for scaling and partitioning + +Best practices for maintaining a high performance when scaling include: + +- Limit the number of $HYPERTABLEs in your $SERVICE_SHORT; having tens of thousands of $HYPERTABLEs is not recommended. +- Choose a strategic chunk size. + +Chunk size affects insert and query performance. You want a chunk small enough +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. The more chunks in the system, the slower that process becomes, even more so +when all those chunks are part of a single hypertable. + + + +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 +to view and set your chunk time intervals, see +[Optimize $HYPERTABLE chunk intervals][change-chunk-intervals]. + +## $HYPERTABLE_CAP indexes + +By default, indexes are automatically created when you create a $HYPERTABLE. The default index is on time, descending. +You can prevent index creation by setting the `create_default_indexes` option to `false`. + +$HYPERTABLE_CAPs have some restrictions on unique constraints and indexes. If you +want a unique index on a $HYPERTABLE, it must include all the partitioning +columns for the table. To learn more, see +[Enforce constraints with unique indexes on $HYPERTABLEs][hypertables-and-unique-indexes]. + +You can prevent index creation by setting the `create_default_indexes` option to `false`. + ## Partition by dimension Partitioning on time is the most common use case for $HYPERTABLE, but it may not be enough for your needs. For example, @@ -44,16 +76,16 @@ you may need to scan for the latest readings that match a certain condition with -The use case for a partitioning dimension is a multi-tenant setup. You isolate the tenants using the `tenant_id` space -partition. However, you must perform extensive testing to ensure this works as expected, and there is a strong risk of -partition explosion, +The use case for a partitioning dimension is a multi-tenant setup. You isolate the tenants using the `tenant_id` space +partition. However, you must perform extensive testing to ensure this works as expected, and there is a strong risk of +partition explosion. -You add a partitioning dimension at the same time as you create the hypertable, when the table is empty. The good news -is that although you select the number of partitions at creation time, as your data grows you can change the number of -partitions later and improve query performance. Changing the number of partitions only affects chunks created after the -change, not existing chunks. To set the number of partitions for a partitioning dimension, call `set_number_partitions`. +You add a partitioning dimension at the same time as you create the hypertable, when the table is empty. The good news +is that although you select the number of partitions at creation time, as your data grows you can change the number of +partitions later and improve query performance. Changing the number of partitions only affects chunks created after the +change, not existing chunks. To set the number of partitions for a partitioning dimension, call `set_number_partitions`. For example: @@ -88,44 +120,6 @@ For example: -## Best practices for scaling and partitioning - -Best practices for maintaining a high performance when scaling include: - -- Limit the number of $HYPERTABLEs in your $SERVICE_SHORT; having tens of thousands of $HYPERTABLEs is not recommended. -- Choose a strategic chunk size. - -Chunk size affects insert and query performance. You want a chunk small enough -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. The more chunks in the system, the slower that process becomes, even more so -when all those chunks are part of a single hypertable. - - - -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 -to view and set your chunk time intervals, see -[Optimize $HYPERTABLE chunk intervals][change-chunk-intervals]. - -## $HYPERTABLE_CAP indexes - -By default, indexes are automatically created when you create a $HYPERTABLE. The default index is on time, descending. -You can prevent index creation by setting the `create_default_indexes` option to `false`. - -$HYPERTABLE_CAPs have some restrictions on unique constraints and indexes. If you -want a unique index on a $HYPERTABLE, it must include all the partitioning -columns for the table. To learn more, see -[Enforce constraints with unique indexes on $HYPERTABLEs][hypertables-and-unique-indexes]. - -You can prevent index creation by setting the `create_default_indexes` option to `false`. - -This section shows you: - -* [Optimize time-series data in hypertables][create-hypertables] -* [Improve hypertable and query performance][change-chunk-intervals] -* [Enforce constraints with unique indexes][hypertables-and-unique-indexes] -* [Troubleshooting][troubleshooting] [about-distributed-hypertables]: /self-hosted/:currentVersion:/distributed-hypertables/about-distributed-hypertables/ [best-practices-space]: #best-practices-for-space-partitioning