> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# max_insert_* 会话设置

> 归于 max_insert_* 自动生成分组的 ClickHouse 会话设置。

export const VersionHistory = ({rows = []}) => {
  if (rows.length === 0) {
    return null;
  }
  const headers = ["版本", "默认值", "注释"];
  const border = "1px solid rgba(128, 128, 128, 0.3)";
  const cell = {
    border,
    padding: "0.25rem 0.5rem",
    textAlign: "start",
    verticalAlign: "top"
  };
  return <details className="not-prose" style={{
    border,
    borderRadius: "0.5rem",
    margin: "0.5rem 0",
    padding: "0.5rem 0.75rem",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <summary style={{
    cursor: "pointer",
    fontWeight: 600,
    opacity: 0.72
  }}>
        版本历史
      </summary>
      <table style={{
    borderCollapse: "collapse",
    width: "100%",
    margin: "0.5rem 0 0"
  }}>
        <thead>
          <tr>
            {headers.map(header => <th key={header} style={{
    ...cell,
    fontWeight: 600,
    opacity: 0.72
  }}>
                {header}
              </th>)}
          </tr>
        </thead>
        <tbody>
          {rows.map((row, row_index) => <tr key={row.id ?? row_index}>
              {(row.items ?? []).map((item, item_index) => <td key={item_index} style={{
    ...cell,
    overflowWrap: "anywhere"
  }}>
                  {item?.label}
                </td>)}
            </tr>)}
        </tbody>
      </table>
    </details>;
};

export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
  return <div className="not-prose" style={{
    display: "flex",
    flexWrap: "wrap",
    alignItems: "baseline",
    columnGap: "0.5rem",
    rowGap: "0.125rem",
    margin: "0.375rem 0",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <div style={{
    fontWeight: 600,
    opacity: 0.72
  }}>类型</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>默认值</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          无需重启即可更改
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

这些设置可在 [system.settings](/zh/reference/system-tables/settings) 中找到，并由 [源代码](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp) 自动生成。

<div id="max_insert_block_size">
  ## max\_insert\_block\_size
</div>

**别名**: `max_insert_block_size_rows`

<SettingsInfoBlock type="NonZeroUInt64" default_value="1048449" />

为插入到表中而生成的块的最大大小 (按行数计) 。

此设置会在以下两种上下文中控制块的生成：

1. 格式解析：当服务器通过任意接口 (HTTP、带内联数据的 clickhouse-client、gRPC、PostgreSQL wire protocol) 解析基于行的输入格式 (CSV、TSV、JSONEachRow 等) 时，会在以下情况下输出块：

   * 同时达到 min\_insert\_block\_size\_rows 和 min\_insert\_block\_size\_bytes，或
   * 达到 max\_insert\_block\_size\_rows 或 max\_insert\_block\_size\_bytes 中的任意一个

   注意：使用 clickhouse-client 或 clickhouse-local 从文件读取时，数据由客户端自身解析，因此此设置适用于客户端。

2. INSERT 操作：在 INSERT 查询期间，以及数据流经 materialized view 时，此设置的行为取决于 `use_strict_insert_block_limits`：

   * 启用时：会在以下情况下输出块：
     * 最小阈值 (AND) ：同时达到 min\_insert\_block\_size\_rows 和 min\_insert\_block\_size\_bytes
     * 最大阈值 (OR) ：达到 max\_insert\_block\_size\_rows 或 max\_insert\_block\_size\_bytes 中的任意一个

   * 禁用时：当达到 min\_insert\_block\_size\_rows 或 min\_insert\_block\_size\_bytes 中的任意一个时，就会输出块。此时不会强制执行 max\_insert\_block\_size 设置。

可能的值：

* 正整数。

<div id="max_insert_block_size_bytes">
  ## max\_insert\_block\_size\_bytes
</div>

<SettingsInfoBlock type="UInt64" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.1"},{"label": "0"},{"label": "新增设置：用于控制在 Row Input Format 中解析数据时按字节计的块大小。"}]}]} />

为插入到表中而生成的块的最大大小 (以字节为单位) 。

此设置与 max\_insert\_block\_size\_rows 配合使用，并在相同上下文中共同控制块的生成。有关这些设置会在何时以及如何应用的详细信息，请参见 max\_insert\_block\_size\_rows。

可能的值：

* 正整数。
* 0 — 该设置不参与块的生成。

<div id="max_insert_delayed_streams_for_parallel_write">
  ## max\_insert\_delayed\_streams\_for\_parallel\_write
</div>

<SettingsInfoBlock type="UInt64" default_value="0" />

延迟最终分片刷写的最大流 (列) 数量。默认值为自动 (如果底层存储支持并行写入，例如 S3，则为 100；否则为禁用)

Cloud 默认值：`50`。

<div id="max_insert_threads">
  ## max\_insert\_threads
</div>

<SettingsInfoBlock type="MaxThreads" default_value="auto(N)" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "0"},{"label": "默认值从 1（不并行执行）改为 auto（0），其值为服务器可用的 CPU 核心数；在内存压力下，会通过 `max_insert_threads_min_free_memory_per_thread` 降低该值。这样，默认会并行执行 `INSERT SELECT`。设为 1 可恢复此前的单线程行为。"}]}]} />

执行 `INSERT` 查询时可使用的最大线程数。

这同时适用于 `INSERT SELECT`，以及通过
`clickhouse-client` 或 HTTP 接口发送数据的普通 `INSERT`。管道的写入端
(合并块并将其写入目标端表) 最多可由这么多线程并行处理。

可能的值：

* 0 — 自动。使用服务器可用的 CPU 核心数 (与 [`max_threads`](/zh/reference/settings/session-settings/max-threads#max_threads) 相同的自动值) ，并会在内存压力下通过 [`max_insert_threads_min_free_memory_per_thread`](/zh/reference/settings/session-settings/max-insert#max_insert_threads_min_free_memory_per_thread) 降低。
* 1 — `INSERT` 在单个线程中执行 (不并行执行) 。使用此值可保留 `INSERT ... SELECT` 的插入顺序。
* 大于 1 的正整数 — 使用指定数量的线程并行执行。

在 26.8 版本之前，默认值为 `1` (不并行执行) 。自 26.8 起，默认值 (`0`) 会解析为 CPU 核心数，因此默认会并行执行 `INSERT`。将 `max_insert_threads` 设为 `1` (或使用 `compatibility` 设置) 可恢复此前的行为。

Cloud 默认值：

* 内存为 8 GiB 的节点使用 `1`
* 内存为 16 GiB 的节点使用 `2`
* 更大规格的节点使用 `4`

仅当 `SELECT` 部分并行执行时，并行 `INSERT SELECT` 才会生效，参见 [`max_threads`](/zh/reference/settings/session-settings/max-threads#max_threads) 设置。
对于普通 `INSERT`，输入数据会以单个流读取和解析，随后管道会调整为这么多个流进行写入。
写入端并行化仅适用于同步普通 `INSERT`：异步插入 ([`async_insert`](/zh/reference/settings/session-settings/async-insert#async_insert) `= 1`) 会存入队列并在后台刷写，因此不受此设置影响，且始终保持单个流。
仅在安全的情况下才会并行化写入端；否则会保持单个流，此设置对其无效。具体来说，在启用 [`use_strict_insert_block_limits`](/zh/reference/settings/session-settings/use#use_strict_insert_block_limits) 时，如果目标端表 (或其转发到的表) 会对插入块去重，且查询已启用插入去重 (参见 [`deduplicate_insert`](/zh/reference/settings/session-settings/deduplicate-insert#deduplicate_insert)) ；如果目标端具有依赖 materialized view (包括目标端转发到的表的视图，例如位于 `Alias` 后的视图) ——除非启用了 [`parallel_view_processing`](/zh/reference/settings/session-settings/parallel#parallel_view_processing)，且依赖视图链不存在去重风险，即视图中的去重已禁用 ([`deduplicate_blocks_in_dependent_materialized_views`](/zh/reference/settings/session-settings/other#deduplicate_blocks_in_dependent_materialized_views)) ，或没有任何依赖视图路径能够去重；以及对于 `Buffer` 和 `Distributed` 目标端，写入都会保持单个流。`Buffer` 会在其自身 Context 中刷写，而 `Distributed` 会将写入转发到远程分片 (该分片本身可能会缓冲数据) ，因此此查询的去重设置不控制最终写入；无论这些设置如何，写入都会保持单个流。非并行 quorum 插入 ([`insert_quorum`](/zh/reference/settings/session-settings/insert-quorum#insert_quorum) 为 `2` 或更大，或为 `'auto'`，且 [`insert_quorum_parallel`](/zh/reference/settings/session-settings/insert-quorum#insert_quorum_parallel) 已禁用) 也会保持单个流，因为每个表只允许存在一个进行中的 quorum 分片。
值越高，内存使用量越大。

<div id="max_insert_threads_min_free_memory_per_thread">
  ## max\_insert\_threads\_min\_free\_memory\_per\_thread
</div>

<SettingsInfoBlock type="UInt64" default_value="4294967296" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.5"},{"label": "4294967296"},{"label": "根据可用空闲内存限制插入线程数量的新设置"}]}]} />

与 `max_threads_min_free_memory_per_thread` 相同，但它作用于 `max_insert_threads`，而不是 `max_threads`。默认值更高，因为插入管道通常比读取管道持有更大的单线程缓冲区 (MergeTree 分片、压缩块) 。

如果空闲内存小于 `max_insert_threads` 与此值的乘积，则会下调 `max_insert_threads` 以满足该限制，最少可降至 `1`。

将其设为 `0` 可禁用此限制。