Skip to content

Commit dc7fe4f

Browse files
billy-the-fishatovpeko
billy-the-fish
and
atovpeko
authored
Add API ref for create_chunk and drop_chunk (#4596)
* chore: update links for the new URL. * chore: update example * review * Update create_chunk.md Signed-off-by: Iain Cox <iain@tigerdata.com> * Update drop_chunk.md Signed-off-by: Iain Cox <iain@tigerdata.com> --------- Signed-off-by: Iain Cox <iain@tigerdata.com> Co-authored-by: atovpeko <anastasiatverdokhleb@gmail.com>
1 parent c2049b6 commit dc7fe4f

File tree

3 files changed

+157
-0
lines changed

3 files changed

+157
-0
lines changed

‎api/hypertable/create_chunk.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
api_name: create_chunk()
3+
excerpt: Create a chunk with specified dimensional constraints
4+
topics: [hypertables]
5+
keywords: [chunks, hypertables, create]
6+
api:
7+
license: community
8+
type: function
9+
products: [cloud, mst, self_hosted]
10+
---
11+
12+
# create_chunk()
13+
14+
Manually create a $CHUNK with specific time ranges and space partition boundaries in a [$HYPERTABLE][hypertable-docs].
15+
16+
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
17+
the new $CHUNK. If necessary, $TIMESCALE_DB renames the table and/or moves the table to the specified schema.
18+
19+
Creating a $CHUNK requires `INSERT` privileges on the $HYPERTABLE. If `chunk_table` is provided, the table must
20+
have the same columns and compatible constraints as the $HYPERTABLE. CHECK constraints must have the same names
21+
as the parent table.
22+
23+
## Samples
24+
25+
- **Create a new $CHUNK for a $HYPERTABLE with a time range**:
26+
27+
```sql
28+
SELECT * FROM _timescaledb_functions.create_chunk(
29+
'conditions',
30+
'{"time": ["2018-01-01 00:00:00", "2018-01-08 00:00:00"]}'
31+
);
32+
```
33+
34+
- **Create a $CHUNK with a custom schema and table name**:
35+
36+
```sql
37+
SELECT * FROM _timescaledb_functions.create_chunk(
38+
'conditions',
39+
'{"time": ["2018-01-08 00:00:00", "2018-01-15 00:00:00"]}',
40+
'custom_schema',
41+
'custom_chunk_name'
42+
);
43+
```
44+
45+
- **Create a $CHUNK from an existing table**:
46+
47+
```sql
48+
-- Create a table with the same structure as your hypertable
49+
CREATE TABLE my_chunk_table (time timestamptz NOT NULL, device int, temp float);
50+
51+
-- Attach it as a chunk
52+
SELECT * FROM _timescaledb_functions.create_chunk(
53+
'conditions',
54+
'{"time": ["2018-01-15 00:00:00", "2018-01-22 00:00:00"]}',
55+
schema_name => 'public',
56+
table_name => 'my_chunk',
57+
chunk_table => 'my_chunk_table'
58+
);
59+
```
60+
61+
- **Create a $CHUNK with space partitioning (advanced)**:
62+
63+
For $HYPERTABLEs with additional space dimensions, specify all dimension constraints:
64+
65+
```sql
66+
SELECT * FROM _timescaledb_functions.create_chunk(
67+
'conditions',
68+
'{"time": ["2018-01-22 00:00:00", "2018-01-29 00:00:00"], "device": [-9223372036854775808, 1073741823]}'
69+
);
70+
```
71+
72+
## Arguments
73+
74+
|Name|Type|Default|Required| Description |
75+
|-|-|-|-|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
76+
|`hypertable`|REGCLASS||✔| The $HYPERTABLE to create the $CHUNK for |
77+
|`slices`|JSONB||✔| A JSONB object specifying the dimensional constraints for the $CHUNK. Specify each dimension with a two-element array `[range_start, range_end]`. <br/><br/>Each key is a dimension column name as defined in `hypertable`, and each value is a two-element array `[range_start, range_end]`. <br/><br/>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. <br/><br/>Specify all dimensions defined in the $HYPERTABLE. For example, `{"time": [1514419200000000, 1515024000000000], "device": [-9223372036854775808, 1073741823]}` |
78+
|`schema_name`|NAME|`NULL`|✖| Schema name for the $CHUNK. If not specified, $TIMESCALE_DB uses the default $CHUNK schema |
79+
|`table_name`|NAME|`NULL`|✖| Table name for the $CHUNK. If not specified, $TIMESCALE_DB generates a default $CHUNK name |
80+
|`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` |
81+
82+
## Returns
83+
84+
|Column|Type| Description |
85+
|-|-|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
86+
|`chunk_id`|INTEGER| The internal ID of the $CHUNK |
87+
|`hypertable_id`|INTEGER| The internal ID of the $HYPERTABLE |
88+
|`schema_name`|NAME| The schema name of the new $CHUNK |
89+
|`table_name`|NAME| The table name of the new $CHUNK |
90+
|`relkind`|CHAR| The relation kind, usually `r` for a regular table |
91+
|`slices`|JSONB| The dimensional constraints that define the $CHUNK |
92+
|`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` |
93+
94+
[hypertable-docs]: /use-timescale/:currentVersion:/hypertables/

‎api/hypertable/drop_chunk.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
api_name: drop_chunk()
3+
excerpt: Drop a single chunk
4+
topics: [hypertables, data retention]
5+
keywords: [chunks, hypertables, drop, delete]
6+
api:
7+
license: community
8+
type: function
9+
products: [cloud, mst, self_hosted]
10+
---
11+
12+
# drop_chunk()
13+
14+
Drop a single $CHUNK from a [$HYPERTABLE][hypertable-docs].
15+
16+
`drop_chunk()` first validates the $CHUNK status, then if it is safe to remove, it removes both the $CHUNK
17+
table and its entry from the $CHUNK catalog.
18+
19+
You cannot drop compressed $CHUNKs directly.
20+
21+
## Samples
22+
23+
- **Drop a specific $CHUNK by name**:
24+
25+
```sql
26+
SELECT _timescaledb_functions.drop_chunk('_timescaledb_internal._hyper_1_2_chunk');
27+
```
28+
29+
- **Drop a $CHUNK using a variable**:
30+
31+
```sql
32+
DO $$
33+
DECLARE
34+
chunk_name regclass;
35+
BEGIN
36+
SELECT show_chunks('conditions', older_than => INTERVAL '6 months')
37+
INTO chunk_name
38+
LIMIT 1;
39+
40+
PERFORM _timescaledb_functions.drop_chunk(chunk_name);
41+
END $$;
42+
```
43+
44+
## Arguments
45+
46+
|Name|Type|Default|Required| Description |
47+
|-|-|-|-|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
48+
|`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. |
49+
50+
## Returns
51+
52+
Returns `true` when the $CHUNK is successfully dropped.
53+
54+
[hypertable-docs]: /use-timescale/:currentVersion:/hypertables/
55+
[drop_chunks]: /api/:currentVersion:/hypertable/drop_chunks/

‎api/page-index/page-index.js‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,14 @@ module.exports = [
3333
title: "drop_chunks",
3434
href: "drop_chunks",
3535
},
36+
{
37+
title: "create_chunk",
38+
href: "create_chunk",
39+
},
40+
{
41+
title: "drop_chunk",
42+
href: "drop_chunk",
43+
},
3644
{
3745
title: "reorder_chunk",
3846
href: "reorder_chunk",

0 commit comments

Comments
 (0)