> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-poc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# enable_chunk_skipping()

> Enable range tracking for columns of chunks from a hypertable

export const HYPERTABLE_CAP = 'Hypertable';

export const CHUNK_CAP = 'Chunk';

export const CHUNK = 'chunk';

export const HYPERTABLE = 'hypertable';

export const COLUMNSTORE = 'columnstore';

export const TIMESCALE_DB = 'TimescaleDB';

<Icon icon="flask" /> Early access <Icon icon="tag" iconType="duotone" /> Since [2.16.0][tsdb-2.16.0]

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 {CHUNK}s created after {CHUNK} skipping is
enabled.

Best practice is to enable range tracking on columns that are correlated to the
partitioning column. In other words, enable tracking on secondary columns which are
referenced in the `WHERE` clauses in your queries.

TimescaleDB supports min/max range tracking for the `smallint`, `int`,
`bigint`, `serial`, `bigserial`, `date`, `timestamp`, and `timestamptz` data types. The
min/max ranges are calculated when a {CHUNK} belonging to
this {HYPERTABLE} is added to the columnstore using the [convert\_to\_columnstore][convert_to_columnstore] function.
The range is stored in start (inclusive) and end (exclusive) form in the
`chunk_column_stats` catalog table.

This way you store the min/max values for such columns in this catalog
table at the per-{CHUNK} level. These min/max range values do
not participate in partitioning of the data. These ranges are
used for {CHUNK} skipping when the `WHERE` clause of an SQL query specifies
ranges on the column.

A [DROP COLUMN][drop-column]
on a column with statistics tracking enabled on it ends up removing all relevant entries
from the catalog table.

A [convert\_to\_rowstore][convert_to_rowstore] invocation on a compressed {CHUNK} resets its entries
from the `chunk_column_stats` catalog table since now it's available for DML and the
min/max range values can change on any further data manipulation in the {CHUNK}.

By default, this feature is disabled. To enable {CHUNK} skipping, set `timescaledb.enable_chunk_skipping = on` in
`postgresql.conf`. When you upgrade from a database instance that uses compression but does not support {CHUNK}
skipping, you need to recompress the previously compressed {CHUNK}s for {CHUNK} skipping to work.

## Samples

In this sample, you create the `conditions` {HYPERTABLE} with partitioning on the `time` column. You then specify and
enable additional columns to track ranges for.

```sql theme={"dark"}
CREATE TABLE conditions (
   time        TIMESTAMPTZ       NOT NULL,
   location    TEXT              NOT NULL,
   device      TEXT              NOT NULL,
   temperature DOUBLE PRECISION  NULL,
   humidity    DOUBLE PRECISION  NULL
) WITH (
   tsdb.hypertable
);

SELECT enable_chunk_skipping('conditions', 'device_id');
```

When you create a {HYPERTABLE} using [CREATE TABLE ... WITH ...][hypertable-create-table], the default partitioning
column is automatically the first column with a timestamp data type. Also, {TIMESCALE_DB} creates a
[columnstore policy][add_columnstore_policy] that automatically converts your data to the {COLUMNSTORE}, after an
interval equal to the value of the [chunk\_interval][create_table_arguments], defined through `compress_after` in the
policy. This columnar format enables fast scanning and
aggregation, optimizing performance for analytical workloads while also saving significant storage space. In the
{COLUMNSTORE} conversion, {HYPERTABLE} {CHUNK}s are compressed by up to 98%, and organized for efficient, large-scale queries.

You can customize this policy later using [alter\_job][alter_job_samples]. However, to change `after` or
`created_before`, the compression settings, or the {HYPERTABLE} the policy is acting on, you must
[remove the columnstore policy][remove_columnstore_policy] and [add a new one][add_columnstore_policy].

You can also manually [convert {CHUNK}s][convert_to_columnstore] in a {HYPERTABLE} to the {COLUMNSTORE}.

[add_columnstore_policy]: /api-reference/timescaledb/hypercore/add_columnstore_policy

[alter_job_samples]: /api-reference/timescaledb/jobs-automation/alter_job#samples

[convert_to_columnstore]: /api-reference/timescaledb/hypercore/convert_to_columnstore

[create_table_arguments]: /api-reference/timescaledb/hypertables/create_table#arguments

[hypertable-create-table]: /api-reference/timescaledb/hypertables/create_table

[remove_columnstore_policy]: /api-reference/timescaledb/hypercore/remove_columnstore_policy

## Arguments

The syntax is:

```sql theme={"dark"}
SELECT enable_chunk_skipping(
    hypertable = '<hypertable_name>',
    column_name = '<column_name>',
    if_not_exists = true | false
);
```

| Name            | Type       | Default | Required | Description                                                                                                           |
| --------------- | ---------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `column_name`   | `NAME`     | -       | ✔        | Column to track range statistics for                                                                                  |
| `hypertable`    | `REGCLASS` | -       | ✔        | {HYPERTABLE} that the column belongs to                                                                               |
| `if_not_exists` | `BOOLEAN`  | `false` | ✖        | Set to `true` so that a notice is sent when ranges are not being tracked for a column. By default, an error is thrown |

## Returns

| Column            | Type    | Description                                                                                           |
| ----------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `column_stats_id` | INTEGER | ID of the entry in the {TIMESCALE_DB} internal catalog                                                |
| `enabled`         | BOOLEAN | Returns `true` when tracking is enabled, `if_not_exists` is `true`, and when a new entry is not added |

[convert_to_columnstore]: /api-reference/timescaledb/hypercore/convert_to_columnstore

[convert_to_rowstore]: /api-reference/timescaledb/hypercore/convert_to_rowstore

[drop-column]: https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-DESC-DROP-COLUMN

[tsdb-2.16.0]: https://github.com/timescale/timescaledb/releases/tag/2.16.0