create_chunk()

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