Skip to main content
Estos ajustes están disponibles en system.merge_tree_settings y se autogeneran a partir del código fuente de ClickHouse.

adaptive_write_buffer_initial_size

Tamaño inicial del búfer de escritura adaptativo

add_implicit_sign_column_constraint_for_collapsing_engine

Si es true, añade una restricción implícita a la columna sign de una tabla CollapsingMergeTree o VersionedCollapsingMergeTree para permitir únicamente valores válidos (1 y -1).

alter_column_secondary_index_mode

Configura si se permiten los comandos ALTER que modifican columnas cubiertas por índices secundarios y qué acción debe realizarse si se permiten. De forma predeterminada, estos comandos ALTER están permitidos y los índices se reconstruyen. Valores posibles:
  • rebuild (predeterminado): Reconstruye cualquier índice secundario afectado por la columna en el comando ALTER.
  • throw: Impide cualquier ALTER de columnas cubiertas por índices secundarios explícitos lanzando una excepción. Los índices implícitos quedan excluidos de esta restricción y se reconstruirán.
  • drop: Elimina los índices secundarios dependientes. Las nuevas partes no tendrán los índices, por lo que será necesario ejecutar MATERIALIZE INDEX para recrearlos.
  • compatibility: Mantiene el comportamiento original: throw en ALTER ... MODIFY COLUMN y rebuild en ALTER ... UPDATE/DELETE.
  • ignore: Pensado para uso experto. Dejará los índices en un estado incoherente, lo que puede dar lugar a resultados de consulta incorrectos.

apply_patches_on_merge

Si es true, las partes de parche se aplican durante las fusiones

assign_part_uuids

Cuando está habilitada, se asignará un identificador único a cada parte nueva. Antes de habilitarla, compruebe que todas las réplicas sean compatibles con UUID versión 4.

auto_statistics_types

Lista separada por comas de los tipos de estadísticas que se calcularán automáticamente en todas las columnas compatibles. Tipos de estadísticas compatibles: basic, tdigest, countmin, uniq, uniq_v2. El tipo de estadísticas minmax está obsoleto: es un subconjunto de basic, que debe usarse en su lugar.

background_task_preferred_step_execution_time_ms

Tiempo objetivo para ejecutar un paso de fusión o mutation. Puede superarse si un paso tarda más

clean_deleted_rows

Configuración obsoleta, no tiene ningún efecto.

clone_replica_zookeeper_create_get_part_batch_size

Tamaño del lote de las solicitudes get-part multi-create de ZooKeeper al clonar una réplica.

compatibility_allow_sampling_expression_not_in_primary_key

Permite crear una tabla con una expresión de muestreo que no forme parte de la clave primaria. Esto solo es necesario para permitir temporalmente ejecutar el servidor con tablas incorrectas por compatibilidad con versiones anteriores.

compute_exact_num_defaults_for_sparse_columns

Calcula el recuento exacto de valores predeterminados por columna durante las inserciones y fusiones, en lugar de la estimación más barata por muestreo que se usa para decidir la serialización dispersa. Lo requiere optimize_trivial_count_with_sparsity_filter, que consume el contador persistido num_defaults (las columnas Nullable además necesitan nullable_serialization_version = 'allow_sparse'). Dejarlo deshabilitado mantiene las inserciones/fusiones tan rápidas como antes; al habilitarlo se añade una pasada O(rows) por cada columna apta para dispersión.

deduplicate_merge_projection_mode

Indica si se permite crear una proyección para una tabla con un MergeTree no clásico, es decir, que no sea un MergeTree (Replicated, Shared). La opción ignore es solo para compatibilidad y puede dar lugar a respuestas incorrectas. En caso contrario, si se permite, define qué acción realizar al fusionar proyecciones: drop o rebuild. Por lo tanto, el MergeTree clásico ignorará esta configuración. También controla OPTIMIZE DEDUPLICATE, pero afecta a todos los miembros de la familia MergeTree. Al igual que la opción lightweight_mutation_projection_mode, también es a nivel de parte. Posibles valores:
  • ignore
  • throw
  • drop
  • rebuild

deduplication_hashes_cache_update_wait_ms

Cuánto tiempo espera cada iteración de inserción a que la caché en memoria deduplication_hashes se actualice a una versión más reciente antes de volver a comprobar si ya contiene bloques insertados. La caché replica el directorio deduplication_hashes en ClickHouse Keeper para que las inserciones puedan detectar duplicados sin una ida y vuelta a Keeper.

default_compression_codec

Especifica el códec de compresión predeterminado que se utilizará si no se ha definido ninguno para una columna concreta en la declaración de la tabla. Orden de selección del códec de compresión para una columna:
  1. Códec de compresión definido para la columna en la declaración de la tabla
  2. Códec de compresión definido en default_compression_codec (esta configuración)
  3. Códec de compresión predeterminado definido en la configuración compression Valor predeterminado: una cadena vacía (no definido).

disco

Nombre del disco de almacenamiento. Se puede especificar en lugar de la política de almacenamiento.

dynamic_serialization_version

Versión de serialización para el tipo de datos Dynamic. Necesaria para la compatibilidad. Valores posibles:
  • v1
  • v2
  • v3

enforce_index_structure_match_on_partition_manipulation

Si esta configuración está habilitada en la tabla de destino de una consulta de manipulación de particiones (ATTACH/MOVE/REPLACE PARTITION), los índices y las proyecciones deben ser idénticos entre las tablas de origen y destino. De lo contrario, la tabla de destino puede tener un superconjunto de los índices y proyecciones de la tabla de origen.

execute_merges_on_single_replica_time_threshold

Cuando esta configuración tiene un valor mayor que cero, solo una réplica inicia la fusión de inmediato, y las demás réplicas esperan hasta ese tiempo para descargar el resultado en lugar de realizar fusiones localmente. Si la réplica elegida no termina la fusión dentro de ese tiempo, se vuelve al comportamiento estándar. Posibles valores:
  • Cualquier entero positivo.

finished_mutations_to_keep

Cuántos registros sobre mutaciones finalizadas se deben conservar. Si es cero, se conservan todos.

force_read_through_cache_for_merges

Forzar la lectura a través de la caché del sistema de archivos para las fusiones

initialization_retry_period

Período de reintento para inicializar la tabla, en segundos.

kill_threads

Configuración obsoleta, no tiene ningún efecto.

lightweight_mutation_projection_mode

De forma predeterminada, la eliminación ligera DELETE no funciona en tablas con proyecciones. Esto se debe a que una operación DELETE puede afectar a las filas de una proyección. Por tanto, el valor predeterminado es throw. Sin embargo, esta opción puede cambiar ese comportamiento. Con el valor drop o rebuild, las eliminaciones funcionarán con proyecciones. drop eliminaría la proyección, por lo que podría ser rápido para la consulta actual, ya que la proyección se elimina, pero lento en consultas futuras, al no haber ninguna proyección disponible. rebuild reconstruiría la proyección, lo que podría afectar al rendimiento de la consulta actual, pero podría acelerar las consultas futuras. Lo bueno es que estas opciones solo funcionarían a nivel de parte, lo que significa que las proyecciones de la parte que no se vea afectada permanecerán intactas en lugar de desencadenar acciones como drop o rebuild. Valores posibles:
  • throw
  • drop
  • rebuild

load_existing_rows_count_for_old_parts

Si se habilita junto con la configuración exclude_deleted_rows_for_part_size_in_merge, el recuento de filas eliminadas de las partes de datos existentes se calculará durante el arranque de la tabla. Tenga en cuenta que esto puede ralentizar la carga de la tabla al arrancar. Valores posibles:
  • true
  • false
Véase también

lock_acquire_timeout_for_background_operations

Para operaciones en segundo plano como fusiones, mutaciones, etc. Número de segundos antes de que falle la adquisición de bloqueos de la tabla.

mutation_workload

Se utiliza para regular cómo se usan y comparten los recursos entre las mutaciones y otras cargas de trabajo. El valor especificado se usa como valor de la configuración workload para las mutaciones en segundo plano de esta tabla. Si no se especifica (cadena vacía), se usa en su lugar la configuración del servidor mutation_workload. Véase también

non_replicated_deduplication_window

El número de los bloques insertados más recientemente en la tabla MergeTree no replicada cuyas sumas hash se almacenan para comprobar duplicados. Posibles valores:
  • Cualquier entero positivo.
  • 0 (desactiva la deduplicación).
Se utiliza un mecanismo de deduplicación similar al de las tablas replicadas (consulte la configuración replicated_deduplication_window): la suma hash de deduplicación cubre todo el bloque insertado. Las sumas hash se escriben en un archivo local en un disco, en lugar de en ClickHouse Keeper.

notify_newest_block_number

Notifica el número del bloque más reciente a SharedJoin o SharedSet. Solo en ClickHouse Cloud.

nullable_serialization_version

Controla el método de serialización que se utiliza para las columnas Nullable(T). Valores posibles:
  • basic — Usa la serialización estándar para Nullable(T).
  • allow_sparse — Permite que Nullable(T) use codificación dispersa.

object_serialization_version

Versión de serialización del tipo de dato JSON. Necesaria para la compatibilidad. Valores posibles:
  • v1
  • v2
  • v3
Solo la versión v3 permite cambiar la versión de serialización de los datos compartidos.

old_parts_lifetime

El tiempo (en segundos) durante el que se almacenan las partes inactivas para proteger contra la pérdida de datos durante reinicios inesperados del servidor. Posibles valores:
  • Cualquier entero positivo.
Después de fusionar varias partes en una nueva parte, ClickHouse marca las partes originales como inactivas y las elimina solo después de que transcurran old_parts_lifetime segundos. Las partes inactivas se eliminan si no están siendo utilizadas por las consultas actuales, es decir, si el refcount de la parte es 1. No se llama a fsync para las partes nuevas, por lo que durante cierto tiempo las partes nuevas existen solo en la RAM del servidor (caché del SO). Si el servidor se reinicia inesperadamente, las partes nuevas pueden perderse o dañarse. Para proteger los datos, las partes inactivas no se eliminan de inmediato. Durante el inicio, ClickHouse comprueba la integridad de las partes. Si la parte fusionada está dañada, ClickHouse devuelve las partes inactivas a la lista de partes activas y más tarde las vuelve a fusionar. Entonces, la parte dañada se renombra (se añade el prefijo broken_) y se mueve a la carpeta detached. Si la parte fusionada no está dañada, las partes inactivas originales se renombran (se añade el prefijo ignored_) y se mueven a la carpeta detached. El valor predeterminado de dirty_expire_centisecs (un ajuste del kernel de Linux) es de 30 segundos (el tiempo máximo durante el que los datos escritos se almacenan solo en RAM), pero con cargas elevadas en el sistema de disco, los datos pueden escribirse mucho más tarde. Según pruebas realizadas, se eligió un valor de 480 segundos para old_parts_lifetime, intervalo durante el cual se garantiza que una parte nueva se escriba en disco.

optimize_row_order

Controla si el orden de las filas debe optimizarse durante las inserciones para mejorar la compresibilidad de la parte de tabla recién insertada. Solo tiene efecto en las tablas ordinarias con motor MergeTree. No hace nada en tablas especializadas con motor MergeTree (p. ej., CollapsingMergeTree). Las tablas MergeTree se comprimen (opcionalmente) usando códecs de compresión. Los códecs de compresión genéricos como LZ4 y ZSTD logran tasas máximas de compresión si los datos presentan patrones. Las secuencias largas del mismo valor suelen comprimirse muy bien. Si esta configuración está habilitada, ClickHouse intenta almacenar los datos en las partes recién insertadas en un orden de filas que minimice el número de secuencias de valores iguales en las columnas de la nueva parte de tabla. En otras palabras, un número pequeño de secuencias de valores iguales significa que las secuencias individuales son largas y se comprimen bien. Encontrar el orden óptimo de las filas es computacionalmente inviable (NP-hard). Por ello, ClickHouse usa una heurística para encontrar rápidamente un orden de filas que, aun así, mejore las tasas de compresión con respecto al orden original de las filas. Si está habilitada, las operaciones de inserción implican costos adicionales de CPU para analizar y optimizar el orden de las filas de los datos nuevos. Se espera que los INSERTs tarden entre un 30 y un 50 % más, según las características de los datos. Las tasas de compresión de LZ4 o ZSTD mejoran en promedio entre un 20 y un 40 %. Esta configuración funciona mejor para tablas sin clave primaria o con una clave primaria de baja cardinalidad, es decir, una tabla con solo unos pocos valores distintos de clave primaria. No se espera que las claves primarias de alta cardinalidad, por ejemplo las que incluyen columnas de timestamp de tipo DateTime64, se beneficien de esta configuración.

packed_skip_index_max_bytes

Umbral (bytes serializados en disco, es decir, después de la compresión y la cadena de hash del subflujo) por debajo del cual un subflujo de índice de omisión se empaqueta en un único archivo skp_idx.packed por parte, en lugar de escribirse como un archivo independiente skp_idx_<name>.idx2 / .mrk2. Los subflujos más grandes permanecen en el formato heredado por archivo. La decisión se toma de forma independiente para cada subflujo en el momento de la escritura, por lo que una sola parte puede tener índices pequeños (por ejemplo, minmax) empaquetados e índices grandes (por ejemplo, un bloom_filter pesado) por archivo. Establézcalo en 0 para desactivar por completo el empaquetado (valor predeterminado). Cada subflujo de índice de omisión consta en realidad de un archivo de datos y un archivo de marcas; ambos se almacenan en búfer en memoria hasta el umbral antes de tomar la decisión de volcado a disco. Por tanto, el pico de memoria durante la escritura escala con 2 * packed_skip_index_max_bytes * (number of substreams that stay below the threshold). Los índices de texto completo no son compatibles con esta configuración y nunca se empaquetan. El empaquetado reduce la presión sobre los inodos cuando hay muchos índices de omisión definidos en una tabla (por ejemplo, con add_minmax_index_for_numeric_columns). El formato en disco es autodescriptivo: los lectores detectan skp_idx.packed y atienden de forma transparente los subflujos empaquetados desde su interior. Cambiar esta configuración afecta solo a las partes nuevas que se escriban; las partes existentes conservan el formato que tenían en el momento de la escritura.

part_minmax_index_columns

Selecciona qué columnas abarca el índice min-max de cada parte. Cada valor habilita un grupo adicional de columnas con respecto al anterior. Valores posibles:
  • partition_key_only — solo se rastrean las columnas de la clave de partición.
  • with_block_number_offset — columnas de la clave de partición, además de las columnas virtuales persistidas _block_number y _block_offset. Habilita la poda a nivel de parte mediante estas columnas.

propagate_types_serialization_versions_to_nested_types

Si está establecido en true, las versiones de serialización como string_serialization_version se propagarán dentro de tipos anidados como Array/Map/Nullable/JSON/etc. Si se desactiva, la versión de serialización se aplicará solo a las columnas de nivel superior de este tipo y Tuple el

ratio_of_defaults_for_sparse_serialization

Relación mínima entre el número de valores por defecto y el número de todos los valores de una columna. Al establecer este valor, la columna se almacena usando serializaciones dispersas. Si una columna es dispersa (contiene principalmente ceros), ClickHouse puede codificarla en un formato disperso y optimizar automáticamente los cálculos: los datos no requieren una descompresión completa durante las consultas. Para habilitar esta serialización dispersa, defina la configuración ratio_of_defaults_for_sparse_serialization con un valor inferior a 1.0. Si el valor es mayor o igual que 1.0, las columnas siempre se escribirán usando la serialización completa normal. Valores posibles:
  • Float entre 0 y 1 para habilitar la serialización dispersa
  • 1.0 (o superior) si no desea usar la serialización dispersa
Ejemplo Observe que la columna s de la siguiente tabla es una cadena vacía en el 95 % de las filas. En my_regular_table no usamos serialización dispersa, y en my_sparse_table establecemos ratio_of_defaults_for_sparse_serialization en 0.95:
Observe que la columna s de my_sparse_table ocupa menos espacio de almacenamiento en disco:
Puede verificar si una columna usa la codificación dispersa consultando la columna serialization_kind de la tabla system.parts_columns:
Puede ver qué partes de s se almacenaron con la serialización dispersa:

reduce_blocking_parts_sleep_ms

Solo disponible en ClickHouse Cloud. Tiempo mínimo de espera antes de volver a intentar reducir las partes bloqueantes después de que no se haya descartado ni reemplazado ningún rango. Un valor más bajo de esta configuración activará tareas en background_schedule_pool con frecuencia, lo que genera una gran cantidad de solicitudes a ZooKeeper en clústeres a gran escala

replace_long_file_name_to_hash

Si el nombre de archivo de una columna es demasiado largo (más de ‘max_file_name_length’ bytes), se reemplaza por SipHash128

replicated_can_become_leader

Si es true, las réplicas de las tablas replicadas de este nodo intentarán asumir el liderazgo. Valores posibles:
  • true
  • false

search_orphaned_parts_disks

ClickHouse examina todos los discos en busca de partes huérfanas al ejecutar cualquier operación ATTACH o CREATE sobre una tabla, para evitar que se pasen por alto partes de datos en discos no definidos (no incluidos en la política). Las partes huérfanas pueden originarse por una reconfiguración del almacenamiento potencialmente insegura; por ejemplo, si se excluyó un disco de la política de almacenamiento. Esta configuración limita el alcance de los discos que se buscarán según sus características. Valores posibles:
  • any - el alcance no está limitado.
  • local - el alcance se limita a los discos locales.
  • none - alcance vacío, no buscar

serialization_info_version

Versión de la información de serialización que se usa al escribir serialization.json. Esta configuración es necesaria para garantizar la compatibilidad durante las actualizaciones del clúster. Valores posibles:
  • basic - Formato básico.
  • with_types - Formato con el campo adicional types_serialization_versions, que permite versiones de serialización por tipo. Esto hace que configuraciones como string_serialization_version tengan efecto.
Durante las actualizaciones progresivas, configúralo como basic para que los servidores nuevos produzcan partes de datos compatibles con los servidores antiguos. Cuando la actualización se complete, cámbialo a WITH_TYPES para habilitar versiones de serialización por tipo.

share_nested_offsets

Cuando está habilitado (valor predeterminado), las columnas Array con nombres con puntos que comparten un prefijo común (p. ej., n.a y n.b) se tratan como parte de una estructura Nested: comparten un único archivo de desplazamiento en disco (p. ej., n.size0), y se valida que sus tamaños de array sean iguales durante INSERT. Cuando está deshabilitado, cada columna Array tiene su propio archivo de desplazamiento independiente, los nombres con puntos no tienen ninguna semántica especial, y una columna escalar puede coexistir con columnas Array con puntos que comparten el mismo prefijo (p. ej., n UInt32 junto con n.a Array(String)). Esta configuración es inmutable después de crear la tabla.

simultaneous_parts_removal_limit

Si hay muchas partes obsoletas, el hilo de limpieza intentará eliminar hasta simultaneous_parts_removal_limit partes en una sola iteración. Si simultaneous_parts_removal_limit se establece en 0, significa que no hay límite.

storage_policy

Nombre de la política de discos de almacenamiento

string_serialization_version

Controla el formato de serialización de las columnas String de nivel superior. Esta configuración solo surte efecto cuando serialization_info_version está configurado como “with_types”. Cuando se configura como with_size_stream, las columnas String de nivel superior se serializan con una subcolumna .size independiente que almacena las longitudes de las cadenas, en lugar de incluirlas en línea. Esto permite subcolumnas .size reales y puede mejorar la eficiencia de compresión. Los tipos String anidados (por ejemplo, dentro de Nullable, LowCardinality, Array o Map) no se ven afectados, excepto cuando aparecen en una Tuple. Valores posibles:
  • single_stream — Usa el formato de serialización estándar con tamaños en línea.
  • with_size_stream — Usa un flujo de tamaños independiente para las columnas String de nivel superior.

temporary_directories_lifetime

Cuántos segundos se deben conservar los directorios tmp_. No debería reducir este valor, porque es posible que las fusiones y mutaciones no puedan funcionar con un valor bajo de este ajuste.

try_fetch_recompressed_part_timeout

Tiempo de espera (en segundos) antes de iniciar la fusión con recompresión. Durante este tiempo, ClickHouse intenta recuperar la parte recomprimida de la réplica a la que se asignó esta fusión con recompresión. La recompresión suele ser lenta en la mayoría de los casos, por lo que no iniciamos la fusión con recompresión hasta que transcurre este tiempo de espera e intentamos recuperar la parte recomprimida de la réplica a la que se asignó esta fusión con recompresión. Valores posibles:
  • Cualquier entero positivo.

ttl_only_drop_parts

Controla si las partes de datos se eliminan por completo en las tablas MergeTree cuando todas las filas de esa parte han caducado según su configuración de TTL. Cuando ttl_only_drop_parts está deshabilitado (de forma predeterminada), solo se eliminan las filas que han caducado según su configuración de TTL. Cuando ttl_only_drop_parts está habilitado, se elimina la parte completa si todas las filas de esa parte han caducado según su configuración de TTL.

wait_for_unique_parts_send_before_shutdown_ms

Antes de apagarse, la tabla esperará el tiempo requerido para que otras réplicas obtengan las partes únicas (que existen solo en la réplica actual) (0 significa deshabilitado).

zookeeper_session_expiration_check_period

Período de comprobación de la expiración de la sesión de ZooKeeper, en segundos. Valores posibles:
  • Cualquier entero positivo.
Última modificación el 24 de julio de 2026