diff --git a/api/hypertable/create_chunk.md b/api/hypertable/create_chunk.md new file mode 100644 index 0000000000..66650a3bdc --- /dev/null +++ b/api/hypertable/create_chunk.md @@ -0,0 +1,94 @@ +--- +api_name: create_chunk() +excerpt: Create a chunk with specified dimensional constraints +topics: [hypertables] +keywords: [chunks, hypertables, create] +api: + license: community + 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, $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 +as the parent table. + +## Samples + +- **Create a new $CHUNK for a $HYPERTABLE with a time range**: + + ```sql + SELECT * FROM _timescaledb_functions.create_chunk( + 'conditions', + '{"time": ["2018-01-01 00:00:00", "2018-01-08 00:00:00"]}' + ); + ``` + +- **Create a $CHUNK with a custom schema and table name**: + + ```sql + SELECT * FROM _timescaledb_functions.create_chunk( + 'conditions', + '{"time": ["2018-01-08 00:00:00", "2018-01-15 00:00:00"]}', + '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": ["2018-01-15 00:00:00", "2018-01-22 00:00:00"]}', + schema_name => 'public', + table_name => 'my_chunk', + chunk_table => 'my_chunk_table' + ); + ``` + +- **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-22 00:00:00", "2018-01-29 00:00:00"], "device": [-9223372036854775808, 1073741823]}' + ); + ``` + +## Arguments + +|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| 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 new file mode 100644 index 0000000000..ffd51db3cc --- /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: community + 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, 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. + +## 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 the $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 3f54f573a2..f10d8eec5e 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",