MergeTree tables settings

## max\_buckets\_in\_map[​](#max_buckets_in_map "Direct link to max_buckets_in_map")

The maximum number of buckets for `Map` serialization. Works with `with_buckets` `Map` serialization.
The actual number of buckets is determined by [map\_buckets\_strategy](#map_buckets_strategy).
The maximum allowed value is 256.

## max\_bytes\_to\_merge\_at\_max\_space\_in\_pool[​](#max_bytes_to_merge_at_max_space_in_pool "Direct link to max_bytes_to_merge_at_max_space_in_pool")

The maximum total parts size (in bytes) to be merged into one part, if there
are enough resources available. Corresponds roughly to the maximum possible
part size created by an automatic background merge. (0 means merges will be disabled)

Possible values:

- Any non-negative integer.

The merge scheduler periodically analyzes the sizes and number of parts in
partitions, and if there are enough free resources in the pool, it starts
background merges. Merges occur until the total size of the source parts is
larger than `max_bytes_to_merge_at_max_space_in_pool`.

Merges initiated by [OPTIMIZE FINAL](/docs/sql-reference/statements/optimize)
ignore `max_bytes_to_merge_at_max_space_in_pool` (only the free disk space
is taken into account).

## max\_bytes\_to\_merge\_at\_min\_space\_in\_pool[​](#max_bytes_to_merge_at_min_space_in_pool "Direct link to max_bytes_to_merge_at_min_space_in_pool")

The maximum total part size (in bytes) to be merged into one part, with the
minimum available resources in the background pool.

Possible values:

- Any positive integer.

`max_bytes_to_merge_at_min_space_in_pool` defines the maximum total size of
parts which can be merged despite the lack of available disk space (in pool).
This is necessary to reduce the number of small parts and the chance of
`Too many parts` errors.
Merges book disk space by doubling the total merged parts sizes.
Thus, with a small amount of free disk space, a situation may occur in which
there is free space, but this space is already booked by ongoing large merges,
so other merges are unable to start, and the number of small parts grows
with every insert.

## max\_cleanup\_delay\_period[​](#max_cleanup_delay_period "Direct link to max_cleanup_delay_period")

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

## max\_compress\_block\_size[​](#max_compress_block_size "Direct link to max_compress_block_size")

The maximum size of blocks of uncompressed data before compressing for writing
to a table. You can also specify this setting in the global settings
(see [max\_compress\_block\_size](/docs/operations/settings/merge-tree-settings#max_compress_block_size)
setting). The value specified when the table is created overrides the global
value for this setting.

## max\_concurrent\_queries[​](#max_concurrent_queries "Direct link to max_concurrent_queries")

Max number of concurrently executed queries related to the MergeTree table.
Queries will still be limited by other `max_concurrent_queries` settings.

Possible values:

- Positive integer.
- `0` — No limit.

Default value: `0` (no limit).

**Example**

```
<max_concurrent_queries>50</max_concurrent_queries>
```

## max\_delay\_to\_insert[​](#max_delay_to_insert "Direct link to max_delay_to_insert")

The value in seconds, which is used to calculate the `INSERT` delay, if the
number of active parts in a single partition exceeds the
[parts\_to\_delay\_insert](#parts_to_delay_insert) value.

Possible values:

- Any positive integer.

The delay (in milliseconds) for `INSERT` is calculated by the formula:

```
max_k = parts_to_throw_insert - parts_to_delay_insert
k = 1 + parts_count_in_partition - parts_to_delay_insert
delay_milliseconds = pow(max_delay_to_insert * 1000, k / max_k)
```

For example, if a partition has 299 active parts and parts\_to\_throw\_insert
= 300, parts\_to\_delay\_insert = 150, max\_delay\_to\_insert = 1, `INSERT` is
delayed for `pow( 1 * 1000, (1 + 299 - 150) / (300 - 150) ) = 1000`
milliseconds.

Starting from version 23.1 formula has been changed to:

```
allowed_parts_over_threshold = parts_to_throw_insert - parts_to_delay_insert
parts_over_threshold = parts_count_in_partition - parts_to_delay_insert + 1
delay_milliseconds = max(min_delay_to_insert_ms, (max_delay_to_insert * 1000)
* parts_over_threshold / allowed_parts_over_threshold)
```

For example, if a partition has 224 active parts and parts\_to\_throw\_insert
= 300, parts\_to\_delay\_insert = 150, max\_delay\_to\_insert = 1,
min\_delay\_to\_insert\_ms = 10, `INSERT` is delayed for `max( 10, 1 * 1000 * (224 - 150 + 1) / (300 - 150) ) = 500` milliseconds.

## max\_delay\_to\_mutate\_ms[​](#max_delay_to_mutate_ms "Direct link to max_delay_to_mutate_ms")

Max delay of mutating MergeTree table in milliseconds, if there are a lot of
unfinished mutations

## max\_digestion\_size\_per\_segment[​](#max_digestion_size_per_segment "Direct link to max_digestion_size_per_segment")

Obsolete setting, does nothing.

## max\_file\_name\_length[​](#max_file_name_length "Direct link to max_file_name_length")

The maximal length of the file name to keep it as is without hashing.
Takes effect only if setting `replace_long_file_name_to_hash` is enabled.
The value of this setting does not include the length of file extension. So,
it is recommended to set it below the maximum filename length (usually 255
bytes) with some gap to avoid filesystem errors.

## max\_files\_to\_modify\_in\_alter\_columns[​](#max_files_to_modify_in_alter_columns "Direct link to max_files_to_modify_in_alter_columns")

Do not apply ALTER if number of files for modification(deletion, addition)
is greater than this setting.

Possible values:

- Any positive integer.

Default value: 75

## max\_files\_to\_remove\_in\_alter\_columns[​](#max_files_to_remove_in_alter_columns "Direct link to max_files_to_remove_in_alter_columns")

Do not apply ALTER, if the number of files for deletion is greater than this
setting.

Possible values:

- Any positive integer.

## max\_merge\_delayed\_streams\_for\_parallel\_write[​](#max_merge_delayed_streams_for_parallel_write "Direct link to max_merge_delayed_streams_for_parallel_write")

The maximum number of streams (columns) that can be flushed in parallel
(analog of max\_insert\_delayed\_streams\_for\_parallel\_write for merges). Works
only for Vertical merges.

## max\_merge\_selecting\_sleep\_ms[​](#max_merge_selecting_sleep_ms "Direct link to max_merge_selecting_sleep_ms")

Maximum time to wait before trying to select parts to merge again after no
parts were selected. A lower setting will trigger selecting tasks in
background\_schedule\_pool frequently which result in large amount of
requests to zookeeper in large-scale clusters

## max\_number\_of\_merges\_with\_ttl\_in\_pool[​](#max_number_of_merges_with_ttl_in_pool "Direct link to max_number_of_merges_with_ttl_in_pool")

When there is
more than specified number of merges with TTL entries in pool, do not assign
new merge with TTL. This is to leave free threads for regular merges and
avoid "Too many parts"

## max\_number\_of\_mutations\_for\_replica[​](#max_number_of_mutations_for_replica "Direct link to max_number_of_mutations_for_replica")

Limit the number of part mutations per replica to the specified amount.
Zero means no limit on the number of mutations per replica (the execution can
still be constrained by other settings).

## max\_part\_loading\_threads[​](#max_part_loading_threads "Direct link to max_part_loading_threads")

Obsolete setting, does nothing.

## max\_part\_removal\_threads[​](#max_part_removal_threads "Direct link to max_part_removal_threads")

Obsolete setting, does nothing.

## max\_partitions\_to\_read[​](#max_partitions_to_read "Direct link to max_partitions_to_read")

Limits the maximum number of partitions that can be accessed in one query.

The setting value specified when the table is created can be overridden via
query-level setting.

Possible values:

- Any positive integer.

You can also specify a query complexity setting [max\_partitions\_to\_read](/docs/operations/settings/settings#max_partitions_to_read)
at a query / session / profile level.