Skip to main content
Эти настройки доступны в system.merge_tree_settings и автоматически генерируются на основе исходного кода ClickHouse.

adaptive_write_buffer_initial_size

Начальный размер адаптивного буфера для записи

add_implicit_sign_column_constraint_for_collapsing_engine

Если значение равно true, добавляет неявное ограничение для столбца sign таблицы CollapsingMergeTree или VersionedCollapsingMergeTree, разрешающее только допустимые значения (1 и -1).

alter_column_secondary_index_mode

Определяет, разрешать ли команды ALTER, изменяющие столбцы, на которые распространяются вторичные индексы, и какое действие выполнять, если они разрешены. По умолчанию такие команды ALTER разрешены, а индексы перестраиваются. Возможные значения:
  • rebuild (по умолчанию): Перестраивает все вторичные индексы, затронутые столбцом в команде ALTER.
  • throw: Запрещает любые команды ALTER для столбцов, на которые распространяются явные вторичные индексы, генерируя исключение. Неявные индексы не подпадают под это ограничение и будут перестроены.
  • drop: Удаляет зависимые вторичные индексы. Новые части не будут содержать эти индексы, и для их повторного создания потребуется MATERIALIZE INDEX.
  • compatibility: Соответствует исходному поведению: throw для ALTER ... MODIFY COLUMN и rebuild для ALTER ... UPDATE/DELETE.
  • ignore: Предназначено для опытных пользователей. Оставляет индексы в несогласованном состоянии, что может привести к некорректным результатам запроса.

apply_patches_on_merge

Если true, патч-части применяются при слияниях

assign_part_uuids

Если параметр включен, каждой новой части присваивается уникальный идентификатор. Перед включением убедитесь, что все реплики поддерживают UUID версии 4.

auto_statistics_types

Разделённый запятыми список типов статистики для автоматического вычисления на всех подходящих столбцах. Поддерживаемые типы статистики: basic, tdigest, countmin, uniq, uniq_v2. Тип статистики minmax устарел: он является подмножеством basic, поэтому вместо него следует использовать basic.

background_task_preferred_step_execution_time_ms

Целевое время выполнения одного шага слияния или мутации. Может быть превышено, если выполнение одного шага занимает больше времени

clean_deleted_rows

Устаревшая настройка, не имеет эффекта.

clone_replica_zookeeper_create_get_part_batch_size

Размер батча для multi-create-запросов get-part к ZooKeeper при клонировании реплики.

compatibility_allow_sampling_expression_not_in_primary_key

Разрешает создавать таблицу с выражением для семплирования, не входящим в первичный ключ. Это нужно только для того, чтобы временно разрешить запуск сервера с некорректными таблицами для обратной совместимости.

compute_exact_num_defaults_for_sparse_columns

Вычислять точное количество значений по умолчанию для каждого столбца во время вставки и слияния, а не использовать более дешёвую оценку на основе сэмплирования, которая применяется при выборе разреженной сериализации. Требуется для optimize_trivial_count_with_sparsity_filter, который использует сохранённый счётчик num_defaults (для столбца с типом Nullable дополнительно требуется nullable_serialization_version = 'allow_sparse'). Если оставить этот параметр отключённым, вставки/слияния останутся такими же быстрыми, как и раньше; при включении добавляется проход O(rows) для каждого столбца, поддерживающего разреженное хранение.

deduplicate_merge_projection_mode

Разрешает или запрещает создавать проекцию для таблицы с неклассическим MergeTree, то есть не с (Replicated, Shared) MergeTree. Вариант ignore предназначен исключительно для совместимости и может приводить к некорректным результатам. В остальных случаях, если это разрешено, задаёт действие при merge проекций: drop или rebuild. Для классического MergeTree эта настройка игнорируется. Она также управляет OPTIMIZE DEDUPLICATE, но действует на все члены семейства MergeTree. Как и параметр lightweight_mutation_projection_mode, она также работает на уровне части. Возможные значения:
  • ignore
  • throw
  • drop
  • rebuild

deduplication_hashes_cache_update_wait_ms

Сколько времени каждая итерация вставки ждёт, пока кэш deduplication_hashes в памяти обновится до более новой версии, прежде чем снова проверять его на наличие уже вставленных блоков. Кэш отражает каталог deduplication_hashes в ClickHouse Keeper, чтобы вставки могли обнаруживать дубликаты без round-trip к Keeper.

default_compression_codec

Указывает кодек сжатия по умолчанию, который используется, если для конкретного столбца в объявлении таблицы он не задан. Порядок выбора кодека сжатия для столбца:
  1. Кодек сжатия, заданный для столбца в объявлении таблицы
  2. Кодек сжатия, заданный в default_compression_codec (эта настройка)
  3. Кодек сжатия по умолчанию, заданный в настройках compression Значение по умолчанию: пустая строка (не задано).

disk

Название диска хранилища. Можно указать вместо политики хранения.

dynamic_serialization_version

Версия сериализации для типа данных Dynamic. Требуется для обеспечения совместимости. Возможные значения:
  • v1
  • v2
  • v3

enforce_index_structure_match_on_partition_manipulation

Если этот параметр включен для целевой таблицы в запросе на манипуляцию с партицией (ATTACH/MOVE/REPLACE PARTITION), индексы и проекции в исходной и целевой таблицах должны быть идентичны. В противном случае целевая таблица может содержать надмножество индексов и проекций исходной таблицы.

execute_merges_on_single_replica_time_threshold

Если значение этой настройки больше нуля, только одна реплика сразу запускает слияние, а остальные реплики ждут в течение этого времени, чтобы скачать результат вместо локального выполнения слияния. Если выбранная реплика не завершит слияние за это время, произойдет возврат к стандартному поведению. Возможные значения:
  • Любое положительное целое число.

finished_mutations_to_keep

Сколько записей о завершённых мутациях хранить. Если ноль, хранить все.

force_read_through_cache_for_merges

Принудительно использовать файловый кэш для чтения при слияниях

initialization_retry_period

Период между повторными попытками инициализации таблицы, в секундах.

kill_threads

Устаревшая настройка, не имеет эффекта.

lightweight_mutation_projection_mode

По умолчанию легковесное удаление DELETE не работает для таблиц с проекциями. Это связано с тем, что операция DELETE может затронуть строки в проекции. Поэтому по умолчанию используется значение throw. Однако этот параметр позволяет изменить поведение. Если задать значение drop или rebuild, операции удаления будут работать с проекциями. drop удаляет проекцию, поэтому это может ускорить текущий запрос, поскольку проекция будет удалена, но замедлить последующие запросы, так как проекция больше не будет доступна. rebuild перестраивает проекцию, что может повлиять на производительность текущего запроса, но может ускорить последующие запросы. Важно, что эти параметры работают только на уровне частей данных: проекции в частях, которые не затрагиваются, останутся нетронутыми, и для них не будут запускаться такие действия, как drop или rebuild. Возможные значения:
  • throw
  • drop
  • rebuild

load_existing_rows_count_for_old_parts

Если этот параметр включен вместе с exclude_deleted_rows_for_part_size_in_merge, при запуске таблицы будет вычисляться количество удаленных строк для существующих частей данных. Обратите внимание, что это может замедлить загрузку таблицы при запуске. Возможные значения:
  • true
  • false
См. также

lock_acquire_timeout_for_background_operations

Для фоновых операций, таких как слияния, мутации и т. д. Определяет, сколько секунд ждать, прежде чем попытка получить блокировку таблицы завершится неудачей.

mutation_workload

Используется для регулирования использования и распределения ресурсов между мутациями и другими рабочими нагрузками. Указанное значение используется в качестве значения настройки workload для фоновых мутаций этой таблицы. Если значение не указано (пустая строка), вместо него используется настройка сервера mutation_workload. См. также

non_replicated_deduplication_window

Количество последних вставленных блоков в нереплицируемой таблице MergeTree, для которых сохраняются хеш-суммы для проверки на наличие дубликатов. Возможные значения:
  • Любое положительное целое число.
  • 0 (отключает дедупликацию).
Используется механизм дедупликации, аналогичный механизму в реплицируемых таблицах (см. настройку replicated_deduplication_window): хеш-сумма дедупликации охватывает весь вставленный блок. Хеш-суммы записываются в локальный файл на диске, а не в ClickHouse Keeper.

notify_newest_block_number

Передавать SharedJoin или SharedSet номер последнего блока. Только в ClickHouse Cloud.

nullable_serialization_version

Определяет метод сериализации для столбцов Nullable(T). Возможные значения:
  • basic — Использовать стандартную сериализацию для Nullable(T).
  • allow_sparse — Разрешить использование разреженного кодирования для Nullable(T).

object_serialization_version

Версия сериализации для типа данных JSON. Необходимо для совместимости. Возможные значения:
  • v1
  • v2
  • v3
Только версия v3 поддерживает изменение версии сериализации общих данных.

old_parts_lifetime

Время хранения неактивных частей (в секундах) для защиты от потери данных при внезапных перезагрузках сервера. Возможные значения:
  • Любое положительное целое число.
После слияния нескольких частей в новую часть ClickHouse помечает исходные части как неактивные и удаляет их только по истечении old_parts_lifetime секунд. Неактивные части удаляются, если они не используются текущими запросами, то есть если refcount части равен 1. Для новых частей fsync не вызывается, поэтому некоторое время они существуют только в оперативной памяти сервера (кэше ОС). Если сервер внезапно перезагрузится, новые части могут быть потеряны или повреждены. Поэтому в целях защиты данных неактивные части не удаляются сразу. При запуске ClickHouse проверяет целостность частей. Если слитая часть повреждена, ClickHouse возвращает неактивные части в список активных и затем снова сливает их. После этого повреждённая часть переименовывается (к ней добавляется префикс broken_) и перемещается в папку detached. Если слитая часть не повреждена, исходные неактивные части переименовываются (к ним добавляется префикс ignored_) и перемещаются в папку detached. Значение dirty_expire_centisecs по умолчанию (параметр ядра Linux) составляет 30 секунд (это максимальное время, в течение которого записанные данные хранятся только в оперативной памяти), однако при высокой нагрузке на дисковую систему данные могут быть записаны значительно позже. Экспериментально для old_parts_lifetime было выбрано значение 480 секунд, в течение которых гарантированно происходит запись новой части на диск.

optimize_row_order

Управляет тем, следует ли оптимизировать порядок строк при вставке, чтобы улучшить сжимаемость вновь вставленной части таблицы. Действует только для обычных таблиц семейства MergeTree. Для специализированных таблиц семейства MergeTree (например, CollapsingMergeTree) не дает никакого эффекта. Таблицы MergeTree могут (опционально) сжиматься с использованием кодеков сжатия. Универсальные кодеки сжатия, такие как LZ4 и ZSTD, обеспечивают максимальную степень сжатия, если в данных есть повторяющиеся закономерности. Длинные серии одинаковых значений обычно сжимаются очень хорошо. Если этот параметр включен, ClickHouse пытается хранить данные в новых вставленных частях в таком порядке строк, который минимизирует число серий равных значений по столбцам новой части таблицы. Иными словами, чем меньше серий равных значений, тем длиннее каждая серия и тем лучше она сжимается. Найти оптимальный порядок строк вычислительно нецелесообразно (NP-трудная задача). Поэтому ClickHouse использует эвристику, чтобы быстро найти такой порядок строк, который все же улучшает степень сжатия по сравнению с исходным порядком. Если параметр включен, операции вставки требуют дополнительных затрат CPU на анализ и оптимизацию порядка строк в новых данных. Ожидается, что INSERT будут выполняться на 30–50% дольше в зависимости от характеристик данных. Степень сжатия LZ4 или ZSTD в среднем улучшается на 20–40%. Этот параметр лучше всего работает для таблиц без первичного ключа или с первичным ключом низкой мощности, то есть для таблиц, имеющих лишь несколько различных значений первичного ключа. Не ожидается, что первичные ключи высокой мощности, например включающие столбцы временных меток типа DateTime64, дадут заметный выигрыш от этого параметра.

packed_skip_index_max_bytes

Порог (сериализованный размер на диске в байтах, то есть после сжатия и цепочки хеширования подстрима), ниже которого подстрим skip-индекса упаковывается в единый архив skp_idx.packed для каждой части вместо записи в отдельные файлы skp_idx_<name>.idx2 / .mrk2. Подстримы большего размера остаются в legacy-структуре с отдельными файлами. Решение принимается независимо для каждого подстрима во время записи, поэтому одна часть может содержать небольшие индексы (например, minmax) в упакованном виде, а крупные (например, тяжёлый bloom_filter) — в отдельных файлах. Установите 0, чтобы полностью отключить упаковку (по умолчанию). Каждый подстрим skip-индекса фактически состоит из файла данных и файла marks; оба буферизуются в памяти до достижения порога, прежде чем принимается решение о spill. Поэтому пиковое потребление памяти при записи масштабируется как 2 * packed_skip_index_max_bytes * (number of substreams that stay below the threshold). Полнотекстовые индексы не поддерживаются этой настройкой и никогда не упаковываются. Упаковка снижает нагрузку на inode, когда для таблицы определено много skip-индексов (например, с add_minmax_index_for_numeric_columns). Формат хранения на диске самоописывающийся: reader обнаруживает skp_idx.packed и прозрачно читает из него упакованные подстримы. Изменение этой настройки влияет только на вновь записанные части; существующие части сохраняют ту структуру, которая была у них на момент записи.

part_minmax_index_columns

Определяет, какие столбцы охватывает min-max индекс для каждой части. Каждое следующее значение добавляет новую группу столбцов к уже включённым ранее. Возможные значения:
  • partition_key_only — отслеживаются только столбцы ключа партиции.
  • with_block_number_offset — столбцы ключа партиции, а также сохранённые виртуальные столбцы _block_number и _block_offset. Включает отсечение на уровне частей по этим столбцам.

propagate_types_serialization_versions_to_nested_types

Если установлено значение true, версии сериализации, такие как string_serialization_version, будут распространяться на вложенные типы, такие как Array/Map/Nullable/JSON/etc. Если параметр отключён, версия сериализации будет применяться только к столбцам верхнего уровня этого типа и Tuple el

ratio_of_defaults_for_sparse_serialization

Минимальное отношение количества значений default к количеству всех значений в столбце. При таком значении настройки столбец будет храниться с использованием разреженной сериализации. Если столбец разреженный (содержит в основном нули), ClickHouse может закодировать его в разреженном формате и автоматически оптимизировать вычисления — данным не потребуется полная распаковка во время выполнения запросов. Чтобы включить эту разреженную сериализацию, задайте для настройки ratio_of_defaults_for_sparse_serialization значение меньше 1.0. Если значение больше или равно 1.0, столбцы всегда будут записываться с использованием обычной полной сериализации. Возможные значения:
  • Float между 0 и 1 для включения разреженной сериализации
  • 1.0 (или больше), если вы не хотите использовать разреженную сериализацию
Пример Обратите внимание, что в следующей таблице столбец s содержит пустую строку в 95% строк. В my_regular_table мы не используем разреженную сериализацию, а в my_sparse_table устанавливаем ratio_of_defaults_for_sparse_serialization равным 0.95:
Обратите внимание, что столбец s в my_sparse_table требует меньше места на диске:
Вы можете проверить, использует ли столбец разреженное кодирование, посмотрев на столбец serialization_kind таблицы system.parts_columns:
Вы можете увидеть, какие части s сохранены с использованием разреженной сериализации:

reduce_blocking_parts_sleep_ms

Доступно только в ClickHouse Cloud. Минимальное время ожидания перед повторной попыткой сократить количество блокирующих частей, если в предыдущий раз не было отброшено/заменено ни одного диапазона. Более низкое значение этого параметра будет часто запускать задачи в background_schedule_pool, что приводит к большому количеству запросов к ZooKeeper в крупных кластерах

replace_long_file_name_to_hash

Если имя файла для столбца слишком длинное (более ‘max_file_name_length’ байт), заменять его на SipHash128

replicated_can_become_leader

Если true, реплики реплицируемых таблиц на этом узле будут пытаться стать лидером. Возможные значения:
  • true
  • false

search_orphaned_parts_disks

ClickHouse сканирует все диски на наличие осиротевших частей при любом ATTACH или CREATE таблицы, чтобы не допустить пропуска частей данных на неопределённых дисках (не входящих в политику хранения). Осиротевшие части появляются в результате потенциально небезопасной реконфигурации хранилища, например если диск был исключён из политики хранения. Эта настройка ограничивает область поиска по характеристикам дисков. Возможные значения:
  • any - область поиска не ограничена.
  • local - область поиска ограничена локальными дисками.
  • none - пустая область, поиск не выполняется

serialization_info_version

Версия информации о сериализации, используемая при записи serialization.json. Эта настройка необходима для обеспечения совместимости во время обновления кластера. Возможные значения:
  • basic - Базовый формат.
  • with_types - Формат с дополнительным полем types_serialization_versions, позволяющий задавать версии сериализации отдельно для каждого типа. Благодаря этому начинают действовать такие настройки, как string_serialization_version.
Во время поэтапных обновлений установите значение basic, чтобы новые серверы создавали части данных, совместимые со старыми серверами. После завершения обновления переключитесь на WITH_TYPES, чтобы включить версии сериализации для каждого типа.

share_nested_offsets

Когда включено (по умолчанию), столбцы типа Array с именами, содержащими точки и имеющими общий префикс (например, n.a и n.b), рассматриваются как часть структуры Nested: они используют один общий файл offsets на диске (например, n.size0), и во время INSERT проверяется, что размеры их массивов совпадают. Когда отключено, каждый столбец типа Array получает собственный независимый файл offsets, имена с точками не имеют специальной семантики, и скалярный столбец может сосуществовать со столбцами типа Array с точками и тем же префиксом (например, n UInt32 вместе с n.a Array(String)). Этот параметр нельзя изменить после создания таблицы.

simultaneous_parts_removal_limit

Если устаревших частей много, поток очистки попытается удалить до simultaneous_parts_removal_limit частей за одну итерацию. Значение simultaneous_parts_removal_limit, равное 0, означает, что ограничений нет.

storage_policy

Имя политики хранения на дисках

string_serialization_version

Управляет форматом сериализации String-столбцов верхнего уровня. Эта настройка действует только в том случае, если serialization_info_version имеет значение “with_types”. Если задано значение with_size_stream, String-столбцы верхнего уровня сериализуются с отдельным подстолбцом .size, в котором хранятся длины строк, а не inline. Это позволяет использовать реальные .size подстолбцы и может повысить эффективность сжатия. Вложенные типы String (например, внутри Nullable, LowCardinality, Array или Map) не затрагиваются, за исключением случаев, когда они находятся в Tuple. Возможные значения:
  • single_stream — Использовать стандартный формат сериализации со встроенными размерами.
  • with_size_stream — Использовать отдельный поток размеров для String-столбцов верхнего уровня.

temporary_directories_lifetime

Сколько секунд хранить каталоги tmp_. Не следует уменьшать это значение, поскольку слияния и мутации могут работать некорректно при низком значении этой настройки.

try_fetch_recompressed_part_timeout

Тайм-аут (в секундах) перед началом слияния с повторным сжатием. В течение этого времени ClickHouse пытается получить part с повторным сжатием с реплики, которой назначено это слияние с повторным сжатием. Повторное сжатие в большинстве случаев выполняется медленно, поэтому до истечения этого тайм-аута слияние с повторным сжатием не запускается, а ClickHouse пытается получить part с повторным сжатием с реплики, которой назначено это слияние с повторным сжатием. Возможные значения:
  • Любое положительное целое число.

ttl_only_drop_parts

Управляет тем, будут ли в таблицах семейства MergeTree полностью удаляться части данных, если все строки в такой части истекли в соответствии с настройками TTL. Когда ttl_only_drop_parts выключен (по умолчанию), удаляются только строки, срок действия которых истек в соответствии с настройками TTL. Когда ttl_only_drop_parts включен, удаляется вся часть, если все строки в ней истекли в соответствии с настройками TTL.

wait_for_unique_parts_send_before_shutdown_ms

Перед завершением работы таблица будет в течение заданного времени ждать, пока уникальные части (существующие только на текущей реплике) не будут получены другими репликами (0 означает, что параметр отключён).

zookeeper_session_expiration_check_period

Период проверки истечения сеанса ZooKeeper в секундах. Возможные значения:
  • Любое положительное целое число.
Последнее изменение 24 июля 2026 г.