create_hypertable()

After creation, all actions, such as ALTER TABLE, SELECT, etc., still work on the resulting hypertable.

Required arguments

tip

If you use SELECT * FROM create_hypertable(...) you get the return value formatted as a table with column headings.

warning

The use of the migrate_data argument to convert a non-empty table can lock the table for a significant amount of time, depending on how much data is in the table. It can also run into deadlock if foreign key constraints exist to other tables.

If you would like finer control over index formation and other aspects of your hypertable, follow these migration instructions instead.

When converting a normal SQL table to a hypertable, pay attention to how you handle constraints. A hypertable can contain foreign keys to normal SQL table columns, but the reverse is not allowed. UNIQUE and PRIMARY constraints must include the partitioning key.

The deadlock is likely to happen when concurrent transactions simultaneously try to insert data into tables that are referenced in the foreign key constraints and into the converting table itself. The deadlock can be prevented by manually obtaining SHARE ROW EXCLUSIVE lock on the referenced tables before calling create_hypertable in the same transaction, see for the syntax.

Units

The ‘time’ column supports the following data types:

tip

The type flexibility of the ‘time’ column allows the use of non-time-based values as the primary chunk partitioning column, as long as those values can increment.

tip

For incompatible data types (for example, jsonb) you can specify a function to the time_partitioning_func argument which can extract a compatible data type

  • For time columns having timestamp or DATE types, the chunk_time_interval should be specified either as an interval type or an integral value in microseconds.

  • For integer types, the chunk_time_interval must be set explicitly, as the database does not otherwise understand the semantics of what each integer value represents (a second, millisecond, nanosecond, etc.). So if your time column is the number of milliseconds since the UNIX epoch, and you wish to have each chunk cover 1 day, you should specify chunk_time_interval => 86400000.

In case of hash partitioning (in other words, if number_partitions is greater than zero), it is possible to optionally specify a custom partitioning function. If no custom partitioning function is specified, the default partitioning function is used. The default partitioning function calls PostgreSQL’s internal hash function for the given type, if one exists. Thus, a custom partitioning function can be used for value types that do not have a native PostgreSQL hash function. A partitioning function should take a single anyelement type argument and return a positive integer hash value. Note that this hash value is not a partition ID, but rather the inserted value’s position in the dimension’s key space, which is then divided across the partitions.

tip

The time column in create_hypertable must be defined as NOT NULL. If this is not already specified on table creation, create_hypertable automatically adds this constraint on the table when it is executed.

Convert table conditions to hypertable with just time partitioning on column time:

Convert table conditions to hypertable, setting chunk_time_interval to 24 hours.

  2. SELECT create_hypertable('conditions', 'time', chunk_time_interval => 86400000000);

Convert table conditions to hypertable with time partitioning on time and space partitioning (4 partitions) on location:

The same as above, but using a custom partitioning function:

  2. SELECT create_hypertable('conditions', 'time', 'location', 4, partitioning_func => 'location_hash');

Convert table conditions to hypertable. Do not raise a warning if conditions is already a hypertable:

  2. CREATE TYPE report AS (reported timestamp with time zone, contents jsonb);
  3. CREATE FUNCTION report_reported(report)
  5.   RETURNS timestamptz
  7.   LANGUAGE SQL
  9.   IMMUTABLE AS
  11.   'SELECT $1.reported';
  13. SELECT create_hypertable('measurements', 'report', time_partitioning_func => 'report_reported');

Time partition table events, on a column type jsonb (event), which has a top level key (started) containing an ISO 8601 formatted timestamp:

Best Practices

One of the most common questions users of TimescaleDB have revolves around configuring .

Time intervals: The current release of TimescaleDB enables both the manual and automated adaption of its time intervals. With manually set intervals, users should specify a chunk_time_interval when creating their hypertable (the default value is 1 week). The interval used for new chunks can be changed by calling set_chunk_time_interval().

The key property of choosing the time interval is that the chunk (including indexes) belonging to the most recent interval (or chunks if using space partitions) fit into memory. As such, we typically recommend setting the interval so that these chunks comprise no more than 25% of main memory.

tip

Make sure that you are planning for recent chunks from all active hypertables to fit into 25% of main memory, rather than 25% per hypertable.

To determine this, you roughly need to understand your data rate. If you are writing roughly 2 GB of data per day and have 64 GB of memory, setting the time interval to a week would be good. If you are writing 10 GB per day on the same machine, setting the time interval to a day would be appropriate. This interval would also hold if data is loaded more in batches - for example, you bulk load 70 GB of data per week, with data corresponding to records from throughout the week.

While it’s generally safer to make chunks smaller rather than too large, setting intervals too small can lead to many chunks, which corresponds to increased planning latency for some types of queries.

tip

One caveat is that the total chunk size is actually dependent on both the underlying data size and any indexes, so some care might be taken if you make heavy use of expensive index types (for example, some PostGIS geospatial indexes). During testing, you might check your total chunk sizes via the function.

Space partitions: In most cases, it is advised for users not to use space partitions. However, if you create a distributed hypertable, it is important to create space partitioning, see create_distributed_hypertable. The rare cases in which space partitions may be useful for non-distributed hypertables are described in the section.