max_insert_* session settings

These settings are available in system.settings and are autogenerated from source.

max_insert_block_size

Aliases: max_insert_block_size_rows

The maximum size of blocks (in a count of rows) to form for insertion into a table.

This setting controls block formation in two contexts:

1. Format parsing: When the server parses row-based input formats (CSV, TSV, JSONEachRow, etc.) from any interface (HTTP, clickhouse-client with inline data, gRPC, PostgreSQL wire protocol), blocks are emitted when:

   • Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached, OR
   • Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached

   Note: When using clickhouse-client or clickhouse-local to read from a file, the client itself parses the data and this setting applies on the client side.

2. INSERT operations: During INSERT queries and when data flows through materialized views, this setting’s behavior depends on use_strict_insert_block_limits:

   • When enabled: Blocks are emitted when:

     • Min thresholds (AND): Both min_insert_block_size_rows AND min_insert_block_size_bytes are reached
     • Max thresholds (OR): Either max_insert_block_size_rows OR max_insert_block_size_bytes is reached

   • When disabled: Blocks are emitted when min_insert_block_size_rows OR min_insert_block_size_bytes is reached. The max_insert_block_size settings are not enforced.

Possible values:

• Positive integer.

max_insert_block_size_bytes

The maximum size of blocks (in bytes) to form for insertion into a table.

This setting works together with max_insert_block_size_rows and controls block formation in the same context. See max_insert_block_size_rows for detailed information about when and how these settings are applied.

Possible values:

• Positive integer.
• 0 — setting does not participate in block formation.

max_insert_delayed_streams_for_parallel_write

The maximum number of streams (columns) to delay final part flush. Default - auto (100 in case of underlying storage supports parallel write, for example S3 and disabled otherwise)

Cloud default value: 50.

max_insert_threads

The maximum number of threads to execute the INSERT query.

This applies both to INSERT SELECT and to a plain INSERT whose data is sent from clickhouse-client or over the HTTP interface. The writing side of the pipeline (squashing the blocks and writing them to the destination table) is parallelized across up to this many threads.

Possible values:

• 0 — Auto. Uses the number of CPU cores available to the server (the same auto value as max_threads), reduced under memory pressure by max_insert_threads_min_free_memory_per_thread.
• 1 — the INSERT is executed in a single thread (no parallel execution). Use this to preserve the insertion order of INSERT ... SELECT.
• Positive integer bigger than 1 — Parallel execution with the specified number of threads.

Before version 26.8 the default was 1 (no parallel execution). Since 26.8 the default (0) resolves to the number of CPU cores, so INSERT is parallelized by default. Set max_insert_threads to 1 (or use the compatibility setting) to restore the previous behavior.

Cloud default value:

• 1 for nodes with 8 GiB memory
• 2 for nodes with 16 GiB memory
• 4 for larger nodes

Parallel INSERT SELECT has effect only if the SELECT part is executed in parallel, see max_threads setting. For a plain INSERT, the input data is read and parsed as a single stream, and the pipeline is then resized to this many streams for writing. The write-side parallelization applies only to synchronous plain INSERTs: asynchronous inserts (async_insert = 1) are stored in a queue and flushed in the background, so they are unaffected by this setting and always stay single-stream. The writing side is parallelized only when it is safe to do so; otherwise it stays single-stream and this setting has no effect on it. In particular, the write is kept single-stream when use_strict_insert_block_limits is enabled, a destination table (or a table it forwards to) deduplicates inserted blocks, and insert deduplication is enabled for the query (see deduplicate_insert), when the destination has dependent materialized views — including views of a table the destination forwards to, e.g. behind an Alias — (unless parallel_view_processing is enabled and the dependent view chains are free of deduplication hazards — deduplication in the views is disabled (deduplicate_blocks_in_dependent_materialized_views) or no dependent view path can deduplicate), and always for Buffer and Distributed destinations. A Buffer flushes in its own context and a Distributed forwards the write to a remote shard (which may itself buffer the data), so this query’s deduplication settings do not govern the final write and it is kept single-stream regardless of them. A non-parallel quorum insert (insert_quorum is 2 or greater, or 'auto', and insert_quorum_parallel is disabled) also stays single-stream, because it permits only one in-flight quorum part per table. Higher values will lead to higher memory usage.

max_insert_threads_min_free_memory_per_thread

Same as max_threads_min_free_memory_per_thread, but applied to max_insert_threads instead of max_threads. The default is higher because insert pipelines typically hold larger per-thread buffers (merge tree parts, compression blocks) than read pipelines.

If the amount of free memory is less than max_insert_threads multiplied by this value, max_insert_threads is reduced to fit, down to a minimum of 1.

Set to 0 to disable this limit.