Troubleshoot hypertables

When something breaks around partitioning, compression, permissions, or chunk lifecycle, these fixes cover the usual failures on hypertables, chunks, and the columnstore.

Can’t create unique index on hypertable, or can’t create hypertable with unique index

Message:

ERROR: cannot create a unique index without the column "<COLUMN_NAME>" (used in partitioning)

You might get a unique index and partitioning column error in 2 situations:

• When creating a primary key or unique index on a hypertable
• When creating a hypertable from a table that already has a unique index or primary key

For more information on how to fix this problem, see the section on creating unique indexes on hypertables.

Reindex hypertables to fix large indexes

Message:

ERROR: invalid attribute number -6 for _hyper_2_839_chunk
CONTEXT: SQL function "hypertable_local_size" statement 1 PL/pgSQL function hypertable_detailed_size(regclass) line 26 at RETURN QUERY SQL function "hypertable_size" statement 1
SQL state: XX000

You might see this error if your hypertable indexes have become very large. To resolve the problem, reindex your hypertables with this command:

REINDEX TABLE _timescaledb_internal._hyper_2_1523284_chunk;

For more information, see the hypertable documentation.

Temporary file size limit exceeded when converting chunks to the columnstore

Message:

ERROR: temporary file size exceeds temp_file_limit

When you try to convert a chunk to the columnstore, especially if the chunk is very large, you could get this error. Compression operations write files to a new compressed chunk table, which is written in temporary memory. The maximum amount of temporary memory available is determined by the temp_file_limit parameter. You can work around this problem by adjusting the temp_file_limit and maintenance_work_mem parameters.

Dropping chunks times out

When you drop a chunk, it requires an exclusive lock. If a chunk is being accessed by another session, you cannot drop the chunk at the same time. If a drop chunk operation can’t get the lock on the chunk, then it times out and the process fails. To resolve this problem, check what is locking the chunk. In some cases, this could be caused by a continuous aggregate or other process accessing the chunk. When the drop chunk operation can get an exclusive lock on the chunk, it completes as expected.

For more information about locks, see the PostgreSQL lock monitoring documentation.

Tuple decompression limit exceeded by operation

Message:

ERROR: tuple decompression limit exceeded by operation

When inserting, updating, or deleting tuples from chunks in the columnstore, it might be necessary to convert tuples to the rowstore. This happens either when you are updating existing tuples or have constraints that need to be verified during insert time. If you happen to trigger a lot of rowstore conversion with a single command, you may end up running out of storage space. For this reason, a limit has been put in place on the number of tuples you can decompress into the rowstore for a single command.

The limit can be increased or turned off (set to 0) like so:

-- set limit to a million tuples
SET timescaledb.max_tuples_decompressed_per_dml_transaction TO 1000000;
-- disable limit by setting to 0
SET timescaledb.max_tuples_decompressed_per_dml_transaction TO 0;

User permissions do not allow chunks to be converted to columnstore or rowstore

Message:

ERROR: must be owner of hypertable "HYPERTABLE_NAME"

You might get this error if you attempt to compress a chunk into the columnstore, or decompress it back into rowstore with a non-privileged user account. To compress or decompress a chunk, your user account must have permissions that allow it to perform CREATE INDEX on the chunk. You can check the permissions of the current user with this command at the psql command prompt:

\dn+ <USERNAME>

To resolve this problem, grant your user account the appropriate privileges with this command:

GRANT PRIVILEGES
    ON TABLE <TABLE_NAME>
    TO <ROLE_TYPE>;

For more information about the GRANT command, see the PostgreSQL documentation.

Low compression rate

Low compression rates are often caused by high cardinality of the segment key. This means that the column you selected for grouping the rows during compression has too many unique values. This makes it impossible to group a lot of rows in a batch. To achieve better compression results, choose a segment key with lower cardinality.

Permission denied when changing ownership of tables and hypertables

Message:

ERROR: permission denied for schema _timescaledb_internal

You might see this error when using the ALTER TABLE command to change the ownership of tables or hypertables.

This use of ALTER TABLE is blocked because the tsdbadmin user is not a superuser.

To change table ownership, use the REASSIGN command instead:

REASSIGN OWNED BY <current_role> TO <desired_role>;