MergeTree tables settings

Possible values:

- `rebuild` (default): Rebuilds any secondary indices affected by the column in the `ALTER` command.
- `throw`: Prevents any `ALTER` of columns covered by **explicit** secondary indices by throwing an exception. Implicit indices are excluded from this restriction and will be rebuilt.
- `drop`: Drop the dependent secondary indices. The new parts won't have the indices, requiring `MATERIALIZE INDEX` to recreate them.
- `compatibility`: Matches the original behaviour: `throw` on `ALTER ... MODIFY COLUMN` and `rebuild` on `ALTER ... UPDATE/DELETE`.
- `ignore`: Intended for expert usage. It will leave the indices in an inconsistent state, allowing incorrect query results.

## always\_fetch\_merged\_part[​](#always_fetch_merged_part "Direct link to always_fetch_merged_part")

If true, this replica never merges parts and always downloads merged parts
from other replicas.

Possible values:

- true, false

## always\_use\_copy\_instead\_of\_hardlinks[​](#always_use_copy_instead_of_hardlinks "Direct link to always_use_copy_instead_of_hardlinks")

Always copy data instead of hardlinking during mutations/replaces/detaches
and so on.

## apply\_patches\_on\_merge[​](#apply_patches_on_merge "Direct link to apply_patches_on_merge")

If true patch parts are applied on merges

## assign\_part\_uuids[​](#assign_part_uuids "Direct link to assign_part_uuids")

When enabled, a unique part identifier will be assigned for every new part.
Before enabling, check that all replicas support UUID version 4.

## async\_block\_ids\_cache\_update\_wait\_ms[​](#async_block_ids_cache_update_wait_ms "Direct link to async_block_ids_cache_update_wait_ms")

How long each insert iteration will wait for async\_block\_ids\_cache update

## async\_insert[​](#async_insert "Direct link to async_insert")

If true, data from INSERT query is stored in queue and later flushed to
table in background.

## auto\_statistics\_types[​](#auto_statistics_types "Direct link to auto_statistics_types")

Comma-separated list of statistics types to calculate automatically on all suitable columns.
Supported statistics types: tdigest, countmin, minmax, uniq.

## background\_task\_preferred\_step\_execution\_time\_ms[​](#background_task_preferred_step_execution_time_ms "Direct link to background_task_preferred_step_execution_time_ms")

Target time to execution of one step of merge or mutation. Can be exceeded if
one step takes longer time

## cache\_populated\_by\_fetch[​](#cache_populated_by_fetch "Direct link to cache_populated_by_fetch")

Note

This setting applies only to ClickHouse Cloud.

When `cache_populated_by_fetch` is disabled (the default setting), new data
parts are loaded into the filesystem cache only when a query is run that requires
those parts.

If enabled, `cache_populated_by_fetch` will instead cause all nodes to load
new data parts from storage into their filesystem cache without requiring a query
to trigger such an action.

**See Also**

- [ignore\_cold\_parts\_seconds](/docs/operations/settings/settings#ignore_cold_parts_seconds)
- [prefer\_warmed\_unmerged\_parts\_seconds](/docs/operations/settings/settings#prefer_warmed_unmerged_parts_seconds)
- [cache\_warmer\_threads](/docs/operations/settings/settings#cache_warmer_threads)

## cache\_populated\_by\_fetch\_filename\_regexp[​](#cache_populated_by_fetch_filename_regexp "Direct link to cache_populated_by_fetch_filename_regexp")

Note

This setting applies only to ClickHouse Cloud.

If not empty, only files that match this regex will be prewarmed into the cache after fetch (if `cache_populated_by_fetch` is enabled).

## check\_delay\_period[​](#check_delay_period "Direct link to check_delay_period")

Obsolete setting, does nothing.

## check\_sample\_column\_is\_correct[​](#check_sample_column_is_correct "Direct link to check_sample_column_is_correct")

Enables the check at table creation, that the data type of a column for s
ampling or sampling expression is correct. The data type must be one of unsigned
[integer types](/docs/sql-reference/data-types/int-uint): `UInt8`, `UInt16`,
`UInt32`, `UInt64`.

Possible values:

- `true` — The check is enabled.
- `false` — The check is disabled at table creation.

Default value: `true`.

By default, the ClickHouse server checks at table creation the data type of
a column for sampling or sampling expression. If you already have tables with
incorrect sampling expression and do not want the server to raise an exception
during startup, set `check_sample_column_is_correct` to `false`.

## clean\_deleted\_rows[​](#clean_deleted_rows "Direct link to clean_deleted_rows")

Obsolete setting, does nothing.

## cleanup\_delay\_period[​](#cleanup_delay_period "Direct link to cleanup_delay_period")

Minimum period to clean old queue logs, blocks hashes and parts.

## cleanup\_delay\_period\_random\_add[​](#cleanup_delay_period_random_add "Direct link to cleanup_delay_period_random_add")

Add uniformly distributed value from 0 to x seconds to cleanup\_delay\_period
to avoid thundering herd effect and subsequent DoS of ZooKeeper in case of
very large number of tables.

## cleanup\_thread\_preferred\_points\_per\_iteration[​](#cleanup_thread_preferred_points_per_iteration "Direct link to cleanup_thread_preferred_points_per_iteration")

Preferred batch size for background cleanup (points are abstract but 1 point
is approximately equivalent to 1 inserted block).

## cleanup\_threads[​](#cleanup_threads "Direct link to cleanup_threads")

Obsolete setting, does nothing.

## clone\_replica\_zookeeper\_create\_get\_part\_batch\_size[​](#clone_replica_zookeeper_create_get_part_batch_size "Direct link to clone_replica_zookeeper_create_get_part_batch_size")

Batch size for ZooKeeper multi-create get-part requests when cloning replica.

## columns\_and\_secondary\_indices\_sizes\_lazy\_calculation[​](#columns_and_secondary_indices_sizes_lazy_calculation "Direct link to columns_and_secondary_indices_sizes_lazy_calculation")

Calculate columns and secondary indices sizes lazily on first request instead
of on table initialization.

## columns\_to\_prewarm\_mark\_cache[​](#columns_to_prewarm_mark_cache "Direct link to columns_to_prewarm_mark_cache")

List of columns to prewarm mark cache for (if enabled). Empty means all columns

## compact\_parts\_max\_bytes\_to\_buffer[​](#compact_parts_max_bytes_to_buffer "Direct link to compact_parts_max_bytes_to_buffer")

Only available in ClickHouse Cloud. Maximal number of bytes to write in a
single stripe in compact parts

## compact\_parts\_max\_granules\_to\_buffer[​](#compact_parts_max_granules_to_buffer "Direct link to compact_parts_max_granules_to_buffer")

Only available in ClickHouse Cloud. Maximal number of granules to write in a
single stripe in compact parts

## compact\_parts\_merge\_max\_bytes\_to\_prefetch\_part[​](#compact_parts_merge_max_bytes_to_prefetch_part "Direct link to compact_parts_merge_max_bytes_to_prefetch_part")

Only available in ClickHouse Cloud. Maximal size of compact part to read it
in a whole to memory during merge.

## compatibility\_allow\_sampling\_expression\_not\_in\_primary\_key[​](#compatibility_allow_sampling_expression_not_in_primary_key "Direct link to compatibility_allow_sampling_expression_not_in_primary_key")

Allow to create a table with sampling expression not in primary key. This is
needed only to temporarily allow to run the server with wrong tables for
backward compatibility.

## compress\_marks[​](#compress_marks "Direct link to compress_marks")

Marks support compression, reduce mark file size and speed up network
transmission.

## compress\_per\_column\_in\_compact\_parts[​](#compress_per_column_in_compact_parts "Direct link to compress_per_column_in_compact_parts")

Controls the physical layout of Compact parts. If true (default), each column in a granule
starts a new compressed block, allowing ClickHouse to skip reading unnecessary columns
from disk. If false, all columns within a granule are packed into the same compressed block,
improving compression ratio but requiring more data to be decompressed during reads.
This is beneficial for workloads that always read all columns (e.g. projections).