> ## 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.

# insert_* 会话设置

> ClickHouse 中 insert_* 自动生成分组里的会话设置。

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="insert_allow_materialized_columns">
  ## insert\_allow\_materialized\_columns
</div>

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

如果启用此设置，则允许在 INSERT 中插入 materialized 列。

<div id="insert_deduplicate">
  ## insert\_deduplicate
</div>

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

启用或禁用 `INSERT` 的块去重 (适用于复制表) 。

可能的值：

* 0 — 禁用。
* 1 — 启用。

默认情况下，通过 `INSERT` 语句插入到复制表中的块会进行去重 (请参见 [Data Replication](/docs/zh/reference/engines/table-engines/mergetree-family/replication)) 。
对于复制表，默认情况下每个分区仅对最近的 100 个块进行去重 (请参见 [replicated\_deduplication\_window](/docs/zh/reference/settings/merge-tree-settings#replicated_deduplication_window)、[replicated\_deduplication\_window\_seconds](/docs/zh/reference/settings/merge-tree-settings#replicated_deduplication_window_seconds)) 。
对于非复制表，请参见 [non\_replicated\_deduplication\_window](/docs/zh/reference/settings/merge-tree-settings#non_replicated_deduplication_window)。

<div id="insert_deduplication_token">
  ## insert\_deduplication\_token
</div>

该设置允许用户在 MergeTree/ReplicatedMergeTree 中自定义去重语义。
例如，在每条 INSERT 语句中为该设置提供一个唯一值，
即可避免相同的插入数据被去重。

可能的值：

* 任意字符串

只有当 `insert_deduplication_token` 非空时，才会将其用于去重。

对于复制表，默认每个分区仅会对最近 100 次插入进行去重 (参见 [replicated\_deduplication\_window](/docs/zh/reference/settings/merge-tree-settings#replicated_deduplication_window)、[replicated\_deduplication\_window\_seconds](/docs/zh/reference/settings/merge-tree-settings#replicated_deduplication_window_seconds)) 。
对于非复制表，请参见 [non\_replicated\_deduplication\_window](/docs/zh/reference/settings/merge-tree-settings#non_replicated_deduplication_window)。

<Note>
  `insert_deduplication_token` 是按分区跟踪的，因此一次 insert 写入的多个分区可以携带相同的 token。若未提供 token，系统默认会基于整个插入块计算内容校验和，因此只有当某次 insert 的全部数据都与之前某次 insert (即重试) 完全一致时，才会被去重；如果只是某个分区中的行恰好与另一条不同的 insert 一致，则不会被去重。
</Note>

示例：

```sql theme={null}
CREATE TABLE test_table
( A Int64 )
ENGINE = MergeTree
ORDER BY A
SETTINGS non_replicated_deduplication_window = 100;

INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (1);

-- the next insert won't be deduplicated because insert_deduplication_token is different
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test1' VALUES (1);

-- the next insert will be deduplicated because insert_deduplication_token
-- is the same as one of the previous
INSERT INTO test_table SETTINGS insert_deduplication_token = 'test' VALUES (2);

SELECT * FROM test_table

┌─A─┐
│ 1 │
└───┘
┌─A─┐
│ 1 │
└───┘
```

<div id="insert_null_as_default">
  ## insert\_null\_as\_default
</div>

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

启用或禁用：向非 [Nullable](/docs/zh/reference/data-types/nullable) 数据类型的列中插入数据时，使用 [默认值](/docs/zh/reference/statements/create/table#default_values) 替代 [NULL](/docs/zh/reference/syntax#null)。
如果列类型不是 Nullable 且此设置被禁用，则插入 `NULL` 会导致异常。如果列类型是 Nullable，则无论此设置如何，`NULL` 值都会按原样插入。

此设置适用于 [INSERT ... SELECT](/docs/zh/reference/statements/insert-into#inserting-the-results-of-select) 查询。请注意，`SELECT` 子查询可以使用 `UNION ALL` 子句进行拼接。

可能的值：

* 0 — 向非 Nullable 列插入 `NULL` 会导致异常。
* 1 — 插入列的默认值而不是 `NULL`。

<div id="insert_shard_id">
  ## insert\_shard\_id
</div>

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

如果不为 `0`，则指定将数据同步插入到 [Distributed](/docs/zh/reference/engines/table-engines/special/distributed) 表中的哪个分片。

如果 `insert_shard_id` 的值不正确，服务器将抛出异常。

要获取 `requested_cluster` 中的分片数量，可以检查服务器配置，或使用以下查询：

```sql theme={null}
SELECT uniq(shard_num) FROM system.clusters WHERE cluster = 'requested_cluster';
```

可能的值：

* 0 — 已禁用。
* 对应的 [Distributed](/docs/zh/reference/engines/table-engines/special/distributed) 表中，从 `1` 到 `shards_num` 之间的任意数字。

**示例**

查询：

```sql theme={null}
CREATE TABLE x AS system.numbers ENGINE = MergeTree ORDER BY number;
CREATE TABLE x_dist AS x ENGINE = Distributed('test_cluster_two_shards_localhost', currentDatabase(), x);
INSERT INTO x_dist SELECT * FROM numbers(5) SETTINGS insert_shard_id = 1;
SELECT * FROM x_dist ORDER BY number ASC;
```

结果：

```text theme={null}
┌─number─┐
│      0 │
│      0 │
│      1 │
│      1 │
│      2 │
│      2 │
│      3 │
│      3 │
│      4 │
│      4 │
└────────┘
```