> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# materialize_statistics_on_insert_* 会话设置

> materialize_statistics_on_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](/docs/zh/reference/system-tables/settings) 中查看，并根据[源代码](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp)自动生成。

<div id="materialize_statistics_on_insert">
  ## materialize\_statistics\_on\_insert
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "1"},{"label": "默认对大小未超过 materialize_statistics_on_insert_max_table_size 的表在 INSERT 时物化列统计信息，以便基于成本的 join 重排序能够为新加载的维度表提供良好的估算。"}]}, {"id": "row-2","items": [{"label": "26.4"},{"label": "0"},{"label": "默认禁用在 INSERT 时构建统计信息，改为依赖合并"}]}, {"id": "row-3","items": [{"label": "24.6"},{"label": "1"},{"label": "新增设置，可禁用在 INSERT 时物化统计信息"}]}]} />

启用时，INSERT 会构建并写入统计信息。禁用时，统计信息将在合并期间或通过显式执行 MATERIALIZE STATISTICS 构建并存储。仅当前大小加上正在写入的块大小不超过 `materialize_statistics_on_insert_max_table_size` 的表会受此设置影响。

<div id="materialize_statistics_on_insert_max_table_size">
  ## materialize\_statistics\_on\_insert\_max\_table\_size
</div>

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

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.8"},{"label": "26843545600"},{"label": "新增设置：仅当表的当前大小与插入块大小之和低于此阈值时，才在 INSERT 时物化列统计信息。previous_value=0（无限制），因此与 26.8 之前版本的 `compatibility` 会恢复原有行为（此 PR 之前没有大小上限，因此显式重新启用 `materialize_statistics_on_insert` 的用户无论表大小如何，都会继续物化统计信息）。"}]}]} />

仅当表中磁盘上活跃 parts 的当前总大小 (压缩后，单位为字节) 与正在写入块的内存中未压缩大小之和不超过此值时，才会在 INSERT 时构建并存储列统计信息 (参见 `materialize_statistics_on_insert`) 。该规则按写入块而非 INSERT 生效：一次 INSERT 会按分区拆分为多个块，每个分区一个块 (对于流式插入，还会拆分为多个块) 。由于正在执行的 INSERT 所产生的 parts 尚未活跃，每个块都会根据已活跃 parts 的大小进行检查。因此，向空表执行一次批量加载时，即使所有 parts 的总大小超过阈值，仍可为其全部构建统计信息；该限制会从后续插入开始生效。使用未压缩块大小 (在写入 part 前无法获知压缩后的大小) 会使检查刻意保持保守，偏差最多为一个块的大小。这样既能使小型维度表的统计信息保持最新状态——这对基于成本的 join 重排序至关重要——又能避免大型事实表每次插入时的额外开销 (其统计信息会在合并期间构建) 。`0` 表示不限制大小。