---
title: create_chunk() | Tiger Data Docs
description: Create a chunk with specified dimensional constraints
---

Manually create a chunk with specific time ranges and space partition boundaries in a hypertable.

You can either create a new chunk, or attach an existing table as a chunk. When you add an existing table, TimescaleDB attaches it to the hypertable and uses it as the data table for the new chunk. If necessary, TimescaleDB 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**:

  ```
  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**:

  ```
  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**:

  ```
  -- 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:

  ```
  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, TimescaleDB uses the default chunk schema                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `table_name`  | NAME     | `NULL`  | ✖        | Table name for the chunk. If not specified, TimescaleDB generates a default chunk name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `chunk_table` | REGCLASS | `NULL`  | ✖        | Attach an existing table as the chunk. TimescaleDB 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` |