Skip to main content

Hypertables

Hypertables are the core feature of TimescaleDB, automatically partitioning your data by time and other dimensions into smaller, more manageable child tables called "chunks." This architecture is the key to achieving fast ingest rates and query performance on large time-series datasets.

Creating a Hypertable​

To convert a standard entity into a hypertable, use the .IsHypertable() method in your entity configuration. You must specify a time column, which will serve as the primary partitioning dimension. By default, chunks are created to cover a time interval of 7 days. You can customize this using the .WithChunkTimeInterval() method.

public class WeatherDataConfiguration : IEntityTypeConfiguration<WeatherData>
{
    public void Configure(EntityTypeBuilder<WeatherData> builder)
    {
        builder.HasKey(x => new { x.Id, x.Time });

        // Convert the table to a hypertable partitioned by 'Time'
        // and set the chunk interval to 1 day.
        builder.IsHypertable(x => x.Time)
               .WithChunkTimeInterval("1 day");
    }
}

Advanced Partitioning with Dimensions​

For very large datasets, you can add secondary partitioning dimensions to further divide your data. This is especially useful for improving query performance by allowing the query planner to prune chunks based on non-time predicates.

Dimensions can be:

  • Range Partitions: Based on a continuous value like another timestamp or a numeric value.
  • Hash Partitions: Based on a discrete value like a device ID or location, spreading the data across a fixed number of partitions.

See also: add_dimension

public class WeatherDataConfiguration : IEntityTypeConfiguration<WeatherData>
{
    public void Configure(EntityTypeBuilder<WeatherData> builder)
    {
        builder.HasKey(e => new { e.Id, e.EventTimestamp, e.OrderPlacedTimestamp, e.WarehouseId });

    builder.IsHypertable(e => e.EventTimestamp)
            .WithChunkTimeInterval("7 days")
            // Add a second time-based dimension
            .HasDimension(Dimension.CreateRange("OrderPlacedTimestamp", "1 month"))
            // Add a space-based dimension for warehouse ID
            .HasDimension(Dimension.CreateHash("WarehouseId", 4));
    }
}

Compression​

Time-series data can be compressed to reduce the amount of storage required, and increase the speed of some queries. This is a cornerstone feature of TimescaleDB. When new data is added to your database, it is in the form of uncompressed rows. TimescaleDB uses a built-in job scheduler to convert this data to the form of compressed columns. This occurs across chunks of TimescaleDB hypertables.

See also: TimescaleDB Compression

public class WeatherDataConfiguration : IEntityTypeConfiguration<WeatherData>
{
    public void Configure(EntityTypeBuilder<WeatherData> builder)
    {
        builder.HasKey(x => new { x.Id, x.Time });
        builder.IsHypertable(x => x.Time).EnableCompression();
    }
}

Chunk skipping​

Enable range statistics for a specific column in a compressed hypertable. This tracks a range of values for that column per chunk. Used for chunk skipping during query optimization and applies only to the chunks created after chunk skipping is enabled.

⚠️ Note: When you use chunk skipping, compression is enabled automatically on the hypertable, as it is a prerequisite.

See also: enable_chunk_skipping

public class WeatherDataConfiguration : IEntityTypeConfiguration<WeatherData>
{
    public void Configure(EntityTypeBuilder<WeatherData> builder)
    {
        builder.HasKey(x => new { x.Id, x.Time });

        // Enable chunk skipping on the 'Time' column.
        // This will also automatically enable compression.
        builder.IsHypertable(x => x.Time)
               .WithChunkSkipping(x => x.Time);
    }
}