From 0b827d60af2d21e44f3307338083b921ea48360b Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Thu, 27 Nov 2025 11:56:25 +0100 Subject: [PATCH 1/5] chore: update links for the new URL. --- api/hypertable/create_chunk.md | 92 ++++++++++++++++++++++++++++++++++ api/hypertable/drop_chunk.md | 55 ++++++++++++++++++++ api/page-index/page-index.js | 8 +++ 3 files changed, 155 insertions(+) create mode 100644 api/hypertable/create_chunk.md create mode 100644 api/hypertable/drop_chunk.md diff --git a/api/hypertable/create_chunk.md b/api/hypertable/create_chunk.md new file mode 100644 index 0000000000..660ec558f0 --- /dev/null +++ b/api/hypertable/create_chunk.md @@ -0,0 +1,92 @@ +--- +api_name: create_chunk() +excerpt: Create a chunk with specified dimensional constraints +topics: [hypertables] +keywords: [chunks, hypertables, create] +api: + license: apache + type: function +products: [cloud, mst, self_hosted] +--- + +# create_chunk() + +Manually create a chunk with specific time ranges and space partition boundaries in a [$HYPERTABLE][hypertable-docs]. + +You can either create a new chunk, or attach an existing table as a chunk. When you add an existing table, it is attached to the $HYPERTABLE and used as the data table for +the new chunk. If necessary, $TIMESCALE_DB renames the table, and/or moves the table to the specified schema. + +Creating a chunk requires `INSERT` privileges on the $HYPERTABLE. If `chunk_table` is provided, the table must +have the same columns and compatible constraints as the $HYPERTABLE. CHECK constraints must have the same names +as the parent table. + +## Samples + +- **Create a new chunk for a $HYPERTABLE with specific time and space constraints**: + + ```sql + SELECT * FROM _timescaledb_functions.create_chunk( + 'conditions', + '{"time": [1514419200000000, 1515024000000000], "device": [-9223372036854775808, 1073741823]}' + ); + ``` + +- **Create a chunk with a custom schema and table name**: + + ```sql + SELECT * FROM _timescaledb_functions.create_chunk( + 'conditions', + '{"time": [1515024000000000, 1519024000000000], "device": [-9223372036854775808, 1073741823]}', + 'custom_schema', + 'custom_chunk_name' + ); + ``` + +- **Create a chunk from an existing table**: + + ```sql + -- Create a table with the same structure as your hypertable + CREATE TABLE my_chunk_table (time timestamptz NOT NULL, device int, temp float); + + -- Attach it as a chunk + SELECT * FROM _timescaledb_functions.create_chunk( + 'conditions', + '{"time": [1519024000000000, 1519628800000000]}', + schema_name => 'public', + table_name => 'my_chunk', + chunk_table => 'my_chunk_table' + ); + ``` + +- **For timestamp dimensions, you can also use string values**: + + ```sql + SELECT * FROM _timescaledb_functions.create_chunk( + 'conditions', + '{"time": ["2018-01-01 00:00:00", "2018-01-08 00:00:00"]}' + ); + ``` + +## Arguments + +|Name|Type|Default|Required| Description | +|-|-|-|-|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`hypertable`|REGCLASS||✔| The $HYPERTABLE_CAP to create the chunk for | +|`slices`|JSONB||✔| A JSONB object specifying the dimensional constraints for the chunk. Each dimension must be specified with a two-element array `[range_start, range_end]`.

Each key is a dimension column name as defined in `hypertable`, and each value is a two-element array `[range_start, range_end]`.

For timestamp dimensions, use numeric values representing microseconds from Unix epoch or ISO 8601 timestamp strings. For example, `"2018-01-01 00:00:00"`). For integer or space dimensions, use numeric values matching the dimension's data type.

All dimensions defined in the $HYPERTABLE must be specified. For example: `{"time": [1514419200000000, 1515024000000000], "device": [-9223372036854775808, 1073741823]}` | +|`schema_name`|NAME|`NULL`|✖| Schema name for the chunk. If not specified, $TIMESCALE_DB uses the default chunk schema | +|`table_name`|NAME|`NULL`|✖| Table name for the chunk. If not specified, $TIMESCALE_DB generates a default chunk name | +|`chunk_table`|REGCLASS|`NULL`|✖| Attach an existing table as the chunk. The table is renamed and/or moved as necessary to match `schema_name` and `table_name` | + +## Returns + +|Column|Type| Description | +|-|-|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`chunk_id`|INTEGER| The internal ID of the chunk | +|`hypertable_id`|INTEGER| The internal ID of the $HYPERTABLE | +|`schema_name`|NAME| Schema name of the new chunk | +|`table_name`|NAME| Table name of the new chunk | +|`relkind`|CHAR| The relation kind (usually 'r' for regular table) | +|`slices`|JSONB| The dimensional constraints that define the chunk | +|`created`|BOOLEAN| `true` if a new chunk was new. If a chunk with the same dimensional constraints already exists, the function returns information about the existing chunk with `created` set to `false` | + +[hypertable-docs]: /use-timescale/:currentVersion:/hypertables/ diff --git a/api/hypertable/drop_chunk.md b/api/hypertable/drop_chunk.md new file mode 100644 index 0000000000..8a658e6f73 --- /dev/null +++ b/api/hypertable/drop_chunk.md @@ -0,0 +1,55 @@ +--- +api_name: drop_chunk() +excerpt: Drop a single chunk +topics: [hypertables, data retention] +keywords: [chunks, hypertables, drop, delete] +api: + license: apache + type: function +products: [cloud, mst, self_hosted] +--- + +# drop_chunk() + +Drop a single chunk from a [$HYPERTABLE][hypertable-docs]. + +`drop_chunk()` first validates the chunk status, if it is safe to remove, it removes both the chunk +table and its entry from the chunk catalog. + +You cannot drop compressed chunks directly. + +## Samples + +- **Drop a specific chunk by name**: + + ```sql + SELECT _timescaledb_functions.drop_chunk('_timescaledb_internal._hyper_1_2_chunk'); + ``` + +- **Drop a chunk using a variable**: + + ```sql + DO $$ + DECLARE + chunk_name regclass; + BEGIN + SELECT show_chunks('conditions', older_than => INTERVAL '6 months') + INTO chunk_name + LIMIT 1; + + PERFORM _timescaledb_functions.drop_chunk(chunk_name); + END $$; + ``` + +## Arguments + +|Name|Type|Default|Required| Description | +|-|-|-|-|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`chunk`|REGCLASS||✔| The name of the chunk to drop. You can use a schema-qualified name, such as `_timescaledb_internal._hyper_1_2_chunk`. If the chunk is in the search path, you can use the unqualified name. | + +## Returns + +Returns `true` when `chunk` is successfully dropped. + +[hypertable-docs]: /use-timescale/:currentVersion:/hypertables/ +[drop_chunks]: /api/:currentVersion:/hypertable/drop_chunks/ diff --git a/api/page-index/page-index.js b/api/page-index/page-index.js index f1b6a38c2a..5627840d48 100644 --- a/api/page-index/page-index.js +++ b/api/page-index/page-index.js @@ -33,6 +33,14 @@ module.exports = [ title: "drop_chunks", href: "drop_chunks", }, + { + title: "create_chunk", + href: "create_chunk", + }, + { + title: "drop_chunk", + href: "drop_chunk", + }, { title: "reorder_chunk", href: "reorder_chunk", From b25a9a9b8e21940ea44363600c19f7912d8943fa Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Tue, 13 Jan 2026 12:58:51 +0100 Subject: [PATCH 2/5] chore: update example --- api/hypertable/create_chunk.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/api/hypertable/create_chunk.md b/api/hypertable/create_chunk.md index 660ec558f0..7ae5f5611e 100644 --- a/api/hypertable/create_chunk.md +++ b/api/hypertable/create_chunk.md @@ -22,12 +22,12 @@ as the parent table. ## Samples -- **Create a new chunk for a $HYPERTABLE with specific time and space constraints**: +- **Create a new chunk for a $HYPERTABLE with a time range**: ```sql SELECT * FROM _timescaledb_functions.create_chunk( 'conditions', - '{"time": [1514419200000000, 1515024000000000], "device": [-9223372036854775808, 1073741823]}' + '{"time": ["2018-01-01 00:00:00", "2018-01-08 00:00:00"]}' ); ``` @@ -36,7 +36,7 @@ as the parent table. ```sql SELECT * FROM _timescaledb_functions.create_chunk( 'conditions', - '{"time": [1515024000000000, 1519024000000000], "device": [-9223372036854775808, 1073741823]}', + '{"time": ["2018-01-08 00:00:00", "2018-01-15 00:00:00"]}', 'custom_schema', 'custom_chunk_name' ); @@ -51,19 +51,21 @@ as the parent table. -- Attach it as a chunk SELECT * FROM _timescaledb_functions.create_chunk( 'conditions', - '{"time": [1519024000000000, 1519628800000000]}', + '{"time": ["2018-01-15 00:00:00", "2018-01-22 00:00:00"]}', schema_name => 'public', table_name => 'my_chunk', chunk_table => 'my_chunk_table' ); ``` -- **For timestamp dimensions, you can also use string values**: +- **Create a chunk with space partitioning (advanced)**: + + For $HYPERTABLES with additional space dimensions, specify all dimension constraints: ```sql SELECT * FROM _timescaledb_functions.create_chunk( 'conditions', - '{"time": ["2018-01-01 00:00:00", "2018-01-08 00:00:00"]}' + '{"time": ["2018-01-22 00:00:00", "2018-01-29 00:00:00"], "device": [-9223372036854775808, 1073741823]}' ); ``` From f79294a18880e8da045b91aee57259d58ad9f08b Mon Sep 17 00:00:00 2001 From: atovpeko Date: Tue, 13 Jan 2026 14:50:20 +0200 Subject: [PATCH 3/5] review --- api/hypertable/create_chunk.md | 52 +++++++++++++++++----------------- api/hypertable/drop_chunk.md | 16 +++++------ 2 files changed, 34 insertions(+), 34 deletions(-) diff --git a/api/hypertable/create_chunk.md b/api/hypertable/create_chunk.md index 7ae5f5611e..1b58196ef2 100644 --- a/api/hypertable/create_chunk.md +++ b/api/hypertable/create_chunk.md @@ -11,18 +11,18 @@ products: [cloud, mst, self_hosted] # create_chunk() -Manually create a chunk with specific time ranges and space partition boundaries in a [$HYPERTABLE][hypertable-docs]. +Manually create a $CHUNK with specific time ranges and space partition boundaries in a [$HYPERTABLE][hypertable-docs]. -You can either create a new chunk, or attach an existing table as a chunk. When you add an existing table, it is attached to the $HYPERTABLE and used as the data table for -the new chunk. If necessary, $TIMESCALE_DB renames the table, and/or moves the table to the specified schema. +You can either create a new $CHUNK, or attach an existing table as a $CHUNK. When you add an existing table, $TIMESCALE_DB attaches it to the $HYPERTABLE and uses it as the data table for +the new $CHUNK. If necessary, $TIMESCALE_DB renames the table and/or moves the table to the specified schema. -Creating a chunk requires `INSERT` privileges on the $HYPERTABLE. If `chunk_table` is provided, the table must -have the same columns and compatible constraints as the $HYPERTABLE. CHECK constraints must have the same names +Creating a $CHUNK requires `INSERT` privileges on the $HYPERTABLE. If `chunk_table` is provided, the table must +have the same columns and compatible constraints as the $HYPERTABLE. CHECK constraints must have the same names as the parent table. ## Samples -- **Create a new chunk for a $HYPERTABLE with a time range**: +- **Create a new $CHUNK for a $HYPERTABLE with a time range**: ```sql SELECT * FROM _timescaledb_functions.create_chunk( @@ -31,7 +31,7 @@ as the parent table. ); ``` -- **Create a chunk with a custom schema and table name**: +- **Create a $CHUNK with a custom schema and table name**: ```sql SELECT * FROM _timescaledb_functions.create_chunk( @@ -42,7 +42,7 @@ as the parent table. ); ``` -- **Create a chunk from an existing table**: +- **Create a $CHUNK from an existing table**: ```sql -- Create a table with the same structure as your hypertable @@ -58,9 +58,9 @@ as the parent table. ); ``` -- **Create a chunk with space partitioning (advanced)**: +- **Create a $CHUNK with space partitioning (advanced)**: - For $HYPERTABLES with additional space dimensions, specify all dimension constraints: + For $HYPERTABLEs with additional space dimensions, specify all dimension constraints: ```sql SELECT * FROM _timescaledb_functions.create_chunk( @@ -71,24 +71,24 @@ as the parent table. ## Arguments -|Name|Type|Default|Required| Description | -|-|-|-|-|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`hypertable`|REGCLASS||✔| The $HYPERTABLE_CAP to create the chunk for | -|`slices`|JSONB||✔| A JSONB object specifying the dimensional constraints for the chunk. Each dimension must be specified with a two-element array `[range_start, range_end]`.

Each key is a dimension column name as defined in `hypertable`, and each value is a two-element array `[range_start, range_end]`.

For timestamp dimensions, use numeric values representing microseconds from Unix epoch or ISO 8601 timestamp strings. For example, `"2018-01-01 00:00:00"`). For integer or space dimensions, use numeric values matching the dimension's data type.

All dimensions defined in the $HYPERTABLE must be specified. For example: `{"time": [1514419200000000, 1515024000000000], "device": [-9223372036854775808, 1073741823]}` | -|`schema_name`|NAME|`NULL`|✖| Schema name for the chunk. If not specified, $TIMESCALE_DB uses the default chunk schema | -|`table_name`|NAME|`NULL`|✖| Table name for the chunk. If not specified, $TIMESCALE_DB generates a default chunk name | -|`chunk_table`|REGCLASS|`NULL`|✖| Attach an existing table as the chunk. The table is renamed and/or moved as necessary to match `schema_name` and `table_name` | +|Name|Type|Default|Required| Description | +|-|-|-|-|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`hypertable`|REGCLASS||✔| The $HYPERTABLE to create the $CHUNK for | +|`slices`|JSONB||✔| A JSONB object specifying the dimensional constraints for the $CHUNK. Specify each dimension with a two-element array `[range_start, range_end]`.

Each key is a dimension column name as defined in `hypertable`, and each value is a two-element array `[range_start, range_end]`.

For timestamp dimensions, use numeric values representing microseconds from Unix epoch or ISO 8601 timestamp strings. For example, `"2018-01-01 00:00:00"`. For integer or space dimensions, use numeric values matching the dimension's data type.

Specify all dimensions defined in the $HYPERTABLE. For example, `{"time": [1514419200000000, 1515024000000000], "device": [-9223372036854775808, 1073741823]}` | +|`schema_name`|NAME|`NULL`|✖| Schema name for the $CHUNK. If not specified, $TIMESCALE_DB uses the default $CHUNK schema | +|`table_name`|NAME|`NULL`|✖| Table name for the $CHUNK. If not specified, $TIMESCALE_DB generates a default $CHUNK name | +|`chunk_table`|REGCLASS|`NULL`|✖| Attach an existing table as the $CHUNK. $TIMESCALE_DB renames and/or moves the table as necessary to match `schema_name` and `table_name` | ## Returns -|Column|Type| Description | -|-|-|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`chunk_id`|INTEGER| The internal ID of the chunk | -|`hypertable_id`|INTEGER| The internal ID of the $HYPERTABLE | -|`schema_name`|NAME| Schema name of the new chunk | -|`table_name`|NAME| Table name of the new chunk | -|`relkind`|CHAR| The relation kind (usually 'r' for regular table) | -|`slices`|JSONB| The dimensional constraints that define the chunk | -|`created`|BOOLEAN| `true` if a new chunk was new. If a chunk with the same dimensional constraints already exists, the function returns information about the existing chunk with `created` set to `false` | +|Column|Type| Description | +|-|-|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|`chunk_id`|INTEGER| The internal ID of the $CHUNK | +|`hypertable_id`|INTEGER| The internal ID of the $HYPERTABLE | +|`schema_name`|NAME| The schema name of the new $CHUNK | +|`table_name`|NAME| The table name of the new $CHUNK | +|`relkind`|CHAR| The relation kind, usually `r` for a regular table | +|`slices`|JSONB| The dimensional constraints that define the $CHUNK | +|`created`|BOOLEAN| `true` if a new $CHUNK was created. If a $CHUNK with the same dimensional constraints already exists, the function returns information about the existing $CHUNK with `created` set to `false` | [hypertable-docs]: /use-timescale/:currentVersion:/hypertables/ diff --git a/api/hypertable/drop_chunk.md b/api/hypertable/drop_chunk.md index 8a658e6f73..e6d2fc7092 100644 --- a/api/hypertable/drop_chunk.md +++ b/api/hypertable/drop_chunk.md @@ -11,22 +11,22 @@ products: [cloud, mst, self_hosted] # drop_chunk() -Drop a single chunk from a [$HYPERTABLE][hypertable-docs]. +Drop a single $CHUNK from a [$HYPERTABLE][hypertable-docs]. -`drop_chunk()` first validates the chunk status, if it is safe to remove, it removes both the chunk -table and its entry from the chunk catalog. +`drop_chunk()` first validates the $CHUNK status, then if it is safe to remove, it removes both the $CHUNK +table and its entry from the $CHUNK catalog. -You cannot drop compressed chunks directly. +You cannot drop compressed $CHUNKs directly. ## Samples -- **Drop a specific chunk by name**: +- **Drop a specific $CHUNK by name**: ```sql SELECT _timescaledb_functions.drop_chunk('_timescaledb_internal._hyper_1_2_chunk'); ``` -- **Drop a chunk using a variable**: +- **Drop a $CHUNK using a variable**: ```sql DO $$ @@ -45,11 +45,11 @@ You cannot drop compressed chunks directly. |Name|Type|Default|Required| Description | |-|-|-|-|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|`chunk`|REGCLASS||✔| The name of the chunk to drop. You can use a schema-qualified name, such as `_timescaledb_internal._hyper_1_2_chunk`. If the chunk is in the search path, you can use the unqualified name. | +|`chunk`|REGCLASS||✔| The name of the $CHUNK to drop. You can use a schema-qualified name, such as `_timescaledb_internal._hyper_1_2_chunk`. If the $CHUNK is in the search path, you can use the unqualified name. | ## Returns -Returns `true` when `chunk` is successfully dropped. +Returns `true` when the $CHUNK is successfully dropped. [hypertable-docs]: /use-timescale/:currentVersion:/hypertables/ [drop_chunks]: /api/:currentVersion:/hypertable/drop_chunks/ From 61d39d88566f2bb20505053e0ffec241512e5b1e Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Wed, 14 Jan 2026 10:49:43 +0100 Subject: [PATCH 4/5] Update create_chunk.md Signed-off-by: Iain Cox --- api/hypertable/create_chunk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/hypertable/create_chunk.md b/api/hypertable/create_chunk.md index 1b58196ef2..66650a3bdc 100644 --- a/api/hypertable/create_chunk.md +++ b/api/hypertable/create_chunk.md @@ -4,7 +4,7 @@ excerpt: Create a chunk with specified dimensional constraints topics: [hypertables] keywords: [chunks, hypertables, create] api: - license: apache + license: community type: function products: [cloud, mst, self_hosted] --- From ae9afbbd85eec190f7802d4bbeb36cdbdcc114b0 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Wed, 14 Jan 2026 10:49:59 +0100 Subject: [PATCH 5/5] Update drop_chunk.md Signed-off-by: Iain Cox --- api/hypertable/drop_chunk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/hypertable/drop_chunk.md b/api/hypertable/drop_chunk.md index e6d2fc7092..ffd51db3cc 100644 --- a/api/hypertable/drop_chunk.md +++ b/api/hypertable/drop_chunk.md @@ -4,7 +4,7 @@ excerpt: Drop a single chunk topics: [hypertables, data retention] keywords: [chunks, hypertables, drop, delete] api: - license: apache + license: community type: function products: [cloud, mst, self_hosted] ---