> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 格式设置
> 用于控制输入和输出格式的设置项。
export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
const cells = [["Type", {type}], ["Default value", {default_value}]];
if (changeable_without_restart) {
const isYes = String(changeable_without_restart).trim().toLowerCase() === "yes";
const badge = isYes ? Yes : No;
cells.push(["Changeable without restart", badge]);
}
return
{cells.map(([h]) => | {h} | )}
{cells.map(([h, v]) => | {v} | )}
;
};
export const galaxyOnClick = eventName => () => {
try {
if (typeof window !== "undefined" && window.galaxy && eventName) {
window.galaxy.track(eventName, {
interaction: "click"
});
}
} catch (e) {}
};
export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
if (link) {
return
Beta
;
}
return ;
};
export const ExperimentalBadge = () => {
return ;
};
这些设置是根据[源文件](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/FormatFactorySettings.h)自动生成的。
## allow\_special\_bool\_values\_inside\_variant
允许将 Variant 类型中的 Bool 值解析自 "on"、"off"、"enable"、"disable" 等特殊的布尔文本值。
## bool\_false\_representation
在 TSV/CSV/Vertical/Pretty 格式中用于表示 Bool 值 false 的文本。
## bool\_true\_representation
在 TSV/CSV/Vertical/Pretty 格式中表示 Bool 值 true 的文本。
## check\_conversion\_from\_numbers\_to\_enum
如果值在 Enum 中不存在，则在将 Numbers 转换为 Enum 时抛出异常。
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
**示例**
```text theme={null}
CREATE TABLE tab (
val Enum('first' = 1, 'second' = 2, 'third' = 3)
) ENGINE = Memory;
INSERT INTO tab SETTINGS check_conversion_from_numbers_to_enum = 1 VALUES (4); -- 返回一个错误
```
## column\_names\_for\_schema\_inference
用于对不包含列名的格式进行 schema inference 时所使用的列名列表。格式为：'column1,column2,column3,...'
## date\_time\_64\_output\_format\_cut\_trailing\_zeros\_align\_to\_groups\_of\_thousands
动态去除 datetime64 值中末尾的零，将输出标度调整为 \[0, 3, 6]，
分别对应“秒”“毫秒”和“微秒”
## date\_time\_input\_format
允许选择日期和时间文本表示的解析器。
此设置不适用于[日期和时间函数](/zh/reference/functions/regular-functions/date-time-functions)。
可能的值：
* `'best_effort'` — 启用扩展解析。
ClickHouse 可以解析基础的 `YYYY-MM-DD HH:MM:SS` 格式以及所有 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) 日期和时间格式。例如，`'2018-06-08T01:02:03.000Z'`。
* `'best_effort_us'` — 与 `best_effort` 类似 (差异请参见 [parseDateTimeBestEffortUS](/zh/reference/functions/regular-functions/type-conversion-functions#parseDateTimeBestEffortUS)
* `'basic'` — 使用基础解析器。
ClickHouse 只能解析基础的 `YYYY-MM-DD HH:MM:SS` 或 `YYYY-MM-DD` 格式。例如，`2019-08-20 10:18:56` 或 `2019-08-20`。
另请参见：
* [DateTime 数据类型。](/zh/reference/data-types/datetime)
* [日期和时间处理函数。](/zh/reference/functions/regular-functions/date-time-functions)
## date\_time\_output\_format
允许为日期和时间的文本表示选择不同的输出格式。
可能的值：
* `simple` - 简单输出格式。
ClickHouse 以 `YYYY-MM-DD hh:mm:ss` 格式输出日期和时间。例如，`2019-08-20 10:18:56`。计算根据数据类型的时区 (如果存在) 或服务器时区进行。
* `iso` - ISO 输出格式。
ClickHouse 以 [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) `YYYY-MM-DDThh:mm:ssZ` 格式输出日期和时间。例如，`2019-08-20T10:18:56Z`。请注意，输出为 UTC (`Z` 表示 UTC) 。
* `unix_timestamp` - Unix 时间戳输出格式。
ClickHouse 以 [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) 格式输出日期和时间。例如，`1566285536`。
另请参阅：
* [DateTime 数据类型。](/zh/reference/data-types/datetime)
* [用于处理日期和时间的函数。](/zh/reference/functions/regular-functions/date-time-functions)
## date\_time\_overflow\_behavior
定义将 [Date](/zh/reference/data-types/date)、[Date32](/zh/reference/data-types/date32)、[DateTime](/zh/reference/data-types/datetime)、[DateTime64](/zh/reference/data-types/datetime64) 或整数转换为 Date、Date32、DateTime 或 DateTime64 时，如果该值无法用结果类型表示，系统应采取的行为。
Possible values:
* `ignore` — 静默忽略溢出。结果未定义。
* `throw` — 发生溢出时抛出异常。
* `saturate` — 对结果执行饱和处理。如果该值小于目标类型可表示的最小值，则结果取最小可表示值；如果该值大于目标类型可表示的最大值，则结果取最大可表示值。
默认值：`ignore`。
## errors\_output\_format
用于将错误写入文本输出的方式。
## format\_avro\_schema\_registry\_connection\_timeout
对于 AvroConfluent 格式：Confluent Schema Registry HTTP 客户端的连接超时时间 (秒) 。同时用于 schema 拉取和 schema 注册。必须大于 0 且小于 600 (10 分钟) 。
## format\_avro\_schema\_registry\_receive\_timeout
对于 AvroConfluent 格式：Confluent Schema Registry HTTP 客户端的接收超时时间 (单位：秒) 。同时用于 schema 拉取和 schema 注册。该值必须大于 0 且小于 600 (10 分钟) 。
## format\_avro\_schema\_registry\_send\_timeout
对于 AvroConfluent 格式：Confluent Schema Registry HTTP 客户端的发送超时，单位为秒。该设置同时用于 schema 拉取和 schema 注册。必须大于 0 且小于 600 (10 分钟) 。
## format\_avro\_schema\_registry\_url
对于 AvroConfluent 格式：Confluent Schema Registry 的 URL。
## format\_binary\_max\_array\_size
RowBinary 格式 中 Array 的最大允许大小。它可防止在数据损坏时分配大量内存。0 表示不受限制
## format\_binary\_max\_object\_size
JSON 类型的 RowBinary 格式中，单个对象允许的最大路径数量。这可防止在数据损坏时分配大量内存。0 表示不受限制
## format\_binary\_max\_string\_size
RowBinary 格式 中 String 的最大允许大小。该设置可在数据损坏时防止分配大量内存。0 表示不受限制
## format\_capn\_proto\_enum\_comparising\_mode
ClickHouse 枚举与 CapnProto 枚举的映射方式
## format\_capn\_proto\_max\_message\_size
单个 CapnProto 消息的最大大小 (以字节为单位) 。这可防止格式错误或损坏的数据导致过量内存分配。默认值为 1 GiB。
## format\_capn\_proto\_use\_autogenerated\_schema
未设置 format\_schema 时，使用自动生成的 CapnProto schema
## format\_csv\_allow\_double\_quotes
如果设置为 true，则允许使用双引号括起字符串。
## format\_csv\_allow\_single\_quotes
如果设置为 true，则允许使用单引号包裹字符串。
## format\_csv\_delimiter
在 CSV 数据中用作分隔符的字符。如果将此设置设为字符串，则该字符串的长度必须为 1。
## format\_csv\_null\_representation
CSV 格式中的自定义 NULL 表示形式
## format\_custom\_escaping\_rule
字段转义规则 (适用于 CustomSeparated 格式)
## format\_custom\_field\_delimiter
字段之间的分隔符 (用于 CustomSeparated 格式)
## format\_custom\_result\_after\_delimiter
结果集后的后缀 (适用于 CustomSeparated 格式)
## format\_custom\_result\_before\_delimiter
结果集前缀 (用于 CustomSeparated 格式)
## format\_custom\_row\_after\_delimiter
最后一列字段后的分隔符 (用于 CustomSeparated 格式)
## format\_custom\_row\_before\_delimiter
CustomSeparated 格式中第一列字段前的分隔符
## format\_custom\_row\_between\_delimiter
行间分隔符 (用于 CustomSeparated 格式)
## format\_display\_secrets\_in\_show\_and\_select
启用或禁用在针对表、数据库、表函数和字典的 `SHOW` 与 `SELECT` 查询中显示 secrets。
希望查看 secrets 的用户，还必须启用
[`display_secrets_in_show_and_select` server setting](/zh/reference/settings/server-settings/settings#display_secrets_in_show_and_select)
并拥有
[`displaySecretsInShowAndSelect`](/zh/reference/statements/grant#displaysecretsinshowandselect) 权限。
Possible values:
* 0 — 已禁用。
* 1 — 已启用。
## format\_json\_object\_each\_row\_column\_for\_object\_name
在 [JSONObjectEachRow](/zh/reference/formats/JSON/JSONObjectEachRow) 格式中，用于存储/写入对象名称的列名。
列类型应为 String。如果值为空，则对象名称将使用默认名称 `row_{i}`。
## format\_protobuf\_use\_autogenerated\_schema
未设置 format\_schema 时，使用自动生成的 Protobuf
## format\_regexp
正则表达式 (用于 Regexp 格式)
## format\_regexp\_escaping\_rule
字段转义规则 (Regexp 格式)
## format\_regexp\_skip\_unmatched
跳过不匹配正则表达式的行 (适用于 Regexp 格式)
## format\_schema
当你使用需要 schema 定义的格式 (例如 [Cap'n Proto](https://capnproto.org/) 或 [Protobuf](https://developers.google.com/protocol-buffers/)) 时，这个参数会很有用。其值取决于所用的格式。
## format\_schema\_message\_name
指定 `format_schema` 中定义的 schema 里所需消息的名称。
为保持与旧版 format\_schema 格式 (`file_name:message_name`) 的兼容性：
* 如果未指定 `format_schema_message_name`，则会从旧版 `format_schema` 值中的 `message_name` 部分推断消息名称。
* 如果在使用旧版格式时指定了 `format_schema_message_name`，则会报错。
## format\_schema\_source
定义 `format_schema` 的来源。
可能的值：
* 'file' (默认) ：`format_schema` 是位于 `format_schemas` 目录中的 schema 文件名。
* 'string'：`format_schema` 是 schema 的字面内容。
* 'query'：`format_schema` 是用于获取 schema 的查询。
当 `format_schema_source` 设置为 'query' 时，需满足以下条件：
* 查询必须恰好返回一个值：即单行单个 String 列。
* 查询结果会被视为 schema 内容。
* 该结果会缓存在本地的 `format_schemas` 目录中。
* 可以使用以下命令清除本地缓存：`SYSTEM DROP FORMAT SCHEMA CACHE FOR Files`。
* 一旦被缓存，相同的查询不会再次执行来获取 schema，直到缓存被显式清除。
* 除了本地缓存文件外，Protobuf 消息也会缓存在内存中。即使清除了本地缓存文件，也必须使用 `SYSTEM DROP FORMAT SCHEMA CACHE [FOR Protobuf]` 清除内存缓存，才能完全刷新 schema。
* 运行查询 `SYSTEM DROP FORMAT SCHEMA CACHE` 可一次性清除缓存文件和 Protobuf 消息 schema 的缓存。
## format\_template\_resultset
包含结果集格式字符串的文件路径 (用于 Template 格式)
## format\_template\_resultset\_format
结果集的 格式字符串 (用于 Template 格式)
## format\_template\_row
包含行格式字符串的文件路径 (用于 Template 格式)
## format\_template\_row\_format
行的格式字符串 (用于 Template 格式)
## format\_template\_rows\_between\_delimiter
行与行之间的分隔符 (用于 Template 格式)
## format\_tsv\_null\_representation
TSV 格式的自定义 NULL 表示形式
## input\_format\_allow\_errors\_num
设置从文本格式 (CSV、TSV 等) 读取数据时可接受的最大错误数。
默认值为 0。
请始终与 `input_format_allow_errors_ratio` 配合使用。
如果在读取行时发生错误，但错误计数仍小于 `input_format_allow_errors_num`，ClickHouse 会忽略该行并继续读取下一行。
如果 `input_format_allow_errors_num` 和 `input_format_allow_errors_ratio` 都超出限制，ClickHouse 会抛出异常。
## input\_format\_allow\_errors\_ratio
设置从文本格式 (CSV、TSV 等) 读取时允许的最大错误比例。
错误比例以 0 到 1 之间的浮点数表示。
默认值为 0。
务必与 `input_format_allow_errors_num` 搭配使用。
如果在读取行时发生错误，但错误计数器仍小于 `input_format_allow_errors_ratio`，ClickHouse 会忽略该行并继续读取下一行。
如果 `input_format_allow_errors_num` 和 `input_format_allow_errors_ratio` 都超出限制，ClickHouse 会抛出异常。
## input\_format\_allow\_seeks
在读取 ORC、Parquet 和 Arrow 输入格式时，允许执行寻道 (或范围读取) 。
启用后，如果数据源支持此功能 (例如本地文件、S3，或支持范围请求且已知大小的 HTTP) ，
ClickHouse 就可以只读取所需的字节范围，并减少内存占用。
禁用后，或者当数据源不支持寻道时 (例如文件大小未知，或流不可寻道) ，
某些读取器可能会回退为将整个文件加载到内存中。
默认启用。
## input\_format\_arrow\_allow\_missing\_columns
读取 Arrow 输入格式时允许缺失列
## input\_format\_arrow\_case\_insensitive\_column\_matching
匹配 Arrow 列与 CH 列时忽略大小写。
## input\_format\_arrow\_skip\_columns\_with\_unsupported\_types\_in\_schema\_inference
在对 Arrow 格式进行 schema inference 时，跳过类型不受支持的列
## input\_format\_avro\_allow\_missing\_fields
对于 Avro/AvroConfluent 格式：如果在 schema 中找不到字段，则使用默认值而不是报错
## input\_format\_avro\_null\_as\_default
对于 Avro/AvroConfluent 格式：当值为 NULL 且列不是 Nullable 时，插入默认值
## input\_format\_binary\_decode\_types\_in\_binary\_format
在 RowBinaryWithNamesAndTypes 输入格式中，以二进制格式读取数据类型，而不是读取类型名称
## input\_format\_binary\_max\_type\_complexity
解码二进制类型时允许的最大类型节点数 (不是深度，而是节点总数) 。`Map(String, UInt32)` = 3 个节点。可防止恶意输入。0 = 无限制。
## input\_format\_binary\_read\_json\_as\_string
在 RowBinary 输入格式中，将 [JSON](/zh/reference/data-types/newjson) 数据类型的值读取为 JSON [String](/zh/reference/data-types/string) 值。
## input\_format\_bson\_skip\_fields\_with\_unsupported\_types\_in\_schema\_inference
在对 BSON 格式进行 schema inference 时，跳过类型不受支持的字段。
## input\_format\_capn\_proto\_skip\_fields\_with\_unsupported\_types\_in\_schema\_inference
对 CapnProto format 进行 schema inference 时，跳过类型不受支持的列
## input\_format\_column\_name\_matching\_mode
定义通过各种格式 (包括但不限于 JSONEachRow、CSVWithNames、JSONColumns、BSONEachRow、RowBinaryWithNames) 摄取数据时列名的匹配模式。
支持的模式：
* match\_case：区分大小写匹配
* ignore\_case：不区分大小写匹配
* auto：先尝试区分大小写匹配；如果失败，则尝试不区分大小写匹配。
## input\_format\_connection\_handling
启用此选项后，如果连接意外关闭，缓冲区中的剩余数据将继续被解析和处理，而不会被视为错误
启用此选项会禁用并行解析，并且无法进行去重
## input\_format\_csv\_allow\_cr\_end\_of\_line
如果设置为 true，则允许行尾使用 \r，且后面不跟
## input\_format\_csv\_allow\_variable\_number\_of\_columns
忽略 CSV 输入中的额外列 (如果文件中的列数超出预期) ，并将 CSV 输入中缺失的字段视为默认值
## input\_format\_csv\_allow\_whitespace\_or\_tab\_as\_delimiter
允许在 CSV 字符串中将空格和制表符(\t)用作字段分隔符
## input\_format\_csv\_arrays\_as\_nested\_csv
从 CSV 读取 Array 时，会假定其元素先按嵌套 CSV 序列化，再放入字符串中。示例："\[""Hello"", ""world"", ""42"""" TV""]"。数组外侧的括号可以省略。
## input\_format\_csv\_deserialize\_separate\_columns\_into\_tuple
如果将其设置为 true，则以 CSV 格式写入的多个独立列可以反序列化为 Tuple 列。
自动检测 CSV 格式中包含名称和类型的表头
## input\_format\_csv\_empty\_as\_default
将 CSV 输入中的空字段按默认值处理。
## input\_format\_csv\_enum\_as\_number
将 CSV 格式中插入的枚举值按枚举索引处理
## input\_format\_csv\_skip\_first\_lines
跳过 CSV 格式数据开头指定数量的行
## input\_format\_csv\_skip\_trailing\_empty\_lines
跳过 CSV 格式末尾的空行
## input\_format\_csv\_trim\_whitespaces
去除 CSV 字符串开头和末尾的空格及制表符 (\t) 字符
## input\_format\_csv\_try\_infer\_numbers\_from\_strings
如果启用，ClickHouse 会在 schema 推断 期间尝试从字符串字段中推断出数值。
如果 CSV 数据中包含带引号的 UInt64 数值，此设置会很有用。
默认禁用。
## input\_format\_csv\_try\_infer\_strings\_from\_quoted\_tuples
将输入数据中带引号的元组解释为 String 类型的值。
## input\_format\_csv\_use\_best\_effort\_in\_schema\_inference
使用一些调整和启发式方法，在 CSV format 中尽力推断 schema
## input\_format\_csv\_use\_default\_on\_bad\_values
允许在 CSV 字段因错误值反序列化失败时，将该列设为默认值
## input\_format\_custom\_allow\_variable\_number\_of\_columns
忽略 CustomSeparated 输入中的多余列 (如果文件中的列数超过预期) ，并将 CustomSeparated 输入中缺失的字段视为默认值
自动检测 CustomSeparated format 中包含名称和类型的标头
## input\_format\_custom\_skip\_trailing\_empty\_lines
跳过 CustomSeparated 格式末尾的空行
## input\_format\_defaults\_for\_omitted\_fields
执行 `INSERT` 查询时，会用相应列的默认值替换被省略的输入列值。此选项适用于 [JSONEachRow](/zh/reference/formats/JSON/JSONEachRow) (以及其他 JSON 格式) 、[CSV](/zh/reference/formats/CSV/CSV)、[TabSeparated](/zh/reference/formats/TabSeparated/TabSeparated)、[TSKV](/zh/reference/formats/TabSeparated/TSKV)、[Parquet](/zh/reference/formats/Parquet/Parquet)、[Arrow](/zh/reference/formats/Arrow/Arrow)、[Avro](/zh/reference/formats/Avro/Avro)、[ORC](/zh/reference/formats/ORC)、[Native](/zh/reference/formats/Native) 格式，以及带有 `WithNames`/`WithNamesAndTypes` 后缀的格式。
启用此选项后，扩展的表元数据会从服务端发送到客户端。这会额外消耗服务端的计算资源，并可能降低性能。
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
## input\_format\_force\_null\_for\_omitted\_fields
强制将省略的字段初始化为 null 值
## input\_format\_hive\_text\_allow\_variable\_number\_of\_columns
忽略 Hive Text 输入中的额外列 (如果文件中的列数超出预期) ，并将 Hive Text 输入中缺失的字段按默认值处理
## input\_format\_hive\_text\_collection\_items\_delimiter
Hive Text File 中集合 (Array 或 Map) 元素之间的分隔符
## input\_format\_hive\_text\_fields\_delimiter
Hive Text File 的字段分隔符
## input\_format\_hive\_text\_map\_keys\_delimiter
Hive Text File 中 map 键值对之间的分隔符
## input\_format\_import\_nested\_json
启用或禁用插入包含嵌套对象的 JSON 数据。
支持的格式：
* [JSONEachRow](/zh/reference/formats/JSON/JSONEachRow)
可能的值：
* 0 — 禁用。
* 1 — 启用。
另请参见：
* `JSONEachRow` 格式中的[嵌套结构用法](/zh/guides/clickhouse/data-formats/json/formats#accessing-nested-json-objects)。
## input\_format\_ipv4\_default\_on\_conversion\_error
IPv4 反序列化时，如果发生转换错误，将使用默认值而不是抛出异常。
默认情况下禁用。
## input\_format\_ipv6\_default\_on\_conversion\_error
在 IPV6 反序列化过程中，如果转换出错，将使用默认值而不是抛出异常。
默认禁用。
## input\_format\_json\_compact\_allow\_variable\_number\_of\_columns
允许 JSONCompact/JSONCompactEachRow 输入格式中的行包含数量可变的列。
对于列数超过预期的行，忽略多余的列；对于缺失列的行，则将其视为默认值。
默认情况下禁用。
## input\_format\_json\_defaults\_for\_missing\_elements\_in\_named\_tuple
在解析命名元组时，如果 JSON 对象中缺少元素，则插入默认值。
此设置仅在启用 `input_format_json_named_tuples_as_objects` 时生效。
默认启用。
## input\_format\_json\_empty\_as\_default
启用后，会将 JSON 输入中的空字段替换为默认值。对于复杂的默认表达式，还必须同时启用 `input_format_defaults_for_omitted_fields`。
可能的值：
* 0 — 禁用。
* 1 — 启用。
## input\_format\_json\_ignore\_unknown\_keys\_in\_named\_tuple
在将 JSON 对象解析为命名元组时，忽略未知键。
默认启用。
## input\_format\_json\_ignore\_unnecessary\_fields
忽略不必要的字段，且不解析这些字段。启用后，对于格式无效或包含重复字段的 JSON 字符串，可能不会抛出异常
## input\_format\_json\_infer\_array\_of\_dynamic\_from\_array\_of\_different\_types
如果启用，则在进行 schema 推断 时，ClickHouse 会对值的数据类型不同的 JSON 数组使用 Array(Dynamic) 类型。
示例：
```sql theme={null}
SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=1;
DESC format(JSONEachRow, '{"a" : [42, "hello", [1, 2, 3]]}');
```
```response theme={null}
┌─name─┬─type───────────┐
│ a │ Array(Dynamic) │
└──────┴────────────────┘
```
```sql theme={null}
SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=0;
DESC format(JSONEachRow, '{"a" : [42, "hello", [1, 2, 3]]}');
```
```response theme={null}
┌─name─┬─type─────────────────────────────────────────────────────────────┐
│ a │ Tuple(Nullable(Int64), Nullable(String), Array(Nullable(Int64))) │
└──────┴──────────────────────────────────────────────────────────────────┘
```
默认启用。
## input\_format\_json\_infer\_incomplete\_types\_as\_strings
在进行 schema 推断 时，对于数据样本中仅包含 `Null`/`{}`/`[]` 的 JSON 键，允许使用 String 类型。
在 JSON 格式 中，任何值都可以读作 String，因此对类型未知的键使用 String 类型，可以避免在 schema 推断 期间出现诸如 `Cannot determine type for column 'column_name' by first 25000 rows of data, most likely this column contains only Nulls or empty Arrays/Maps` 之类的错误。
示例：
```sql theme={null}
SET input_format_json_infer_incomplete_types_as_strings = 1, input_format_json_try_infer_named_tuples_from_objects = 1;
DESCRIBE format(JSONEachRow, '{"obj" : {"a" : [1,2,3], "b" : "hello", "c" : null, "d" : {}, "e" : []}}');
SELECT * FROM format(JSONEachRow, '{"obj" : {"a" : [1,2,3], "b" : "hello", "c" : null, "d" : {}, "e" : []}}');
```
结果：
```
┌─name─┬─type───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ obj │ Tuple(a Array(Nullable(Int64)), b Nullable(String), c Nullable(String), d Nullable(String), e Array(Nullable(String))) │ │ │ │ │ │
└──────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
┌─obj────────────────────────────┐
│ ([1,2,3],'hello',NULL,'{}',[]) │
└────────────────────────────────┘
```
默认启用。
## input\_format\_json\_map\_as\_array\_of\_tuples
将 Map 列反序列化为由 Tuple 构成的 JSON 数组。
默认禁用。
## input\_format\_json\_max\_depth
JSON 中字段的最大嵌套深度。这不是硬性限制，不要求严格精确地应用。
## input\_format\_json\_named\_tuples\_as\_objects
将命名元组列按 JSON 对象进行解析。
默认启用。
## input\_format\_json\_read\_arrays\_as\_strings
允许在 JSON 输入格式中将 JSON 数组解析为字符串。
示例：
```sql theme={null}
SET input_format_json_read_arrays_as_strings = 1;
SELECT arr, toTypeName(arr), JSONExtractArrayRaw(arr)[3] from format(JSONEachRow, 'arr String', '{"arr" : [1, "Hello", [1,2,3]]}');
```
结果：
```
┌─arr───────────────────┬─toTypeName(arr)─┬─arrayElement(JSONExtractArrayRaw(arr), 3)─┐
│ [1, "Hello", [1,2,3]] │ String │ [1,2,3] │
└───────────────────────┴─────────────────┴───────────────────────────────────────────┘
```
默认启用。
## input\_format\_json\_read\_bools\_as\_numbers
允许在 JSON 输入格式中将布尔值按数字解析。
默认启用。
## input\_format\_json\_read\_bools\_as\_strings
允许在 JSON 输入格式中将布尔值按字符串解析。
默认启用。
## input\_format\_json\_read\_numbers\_as\_strings
允许在 JSON 输入格式中将数字解析为字符串。
默认启用。
## input\_format\_json\_read\_objects\_as\_strings
允许在 JSON 输入格式中将 JSON 对象作为字符串解析。
示例：
```sql theme={null}
SET input_format_json_read_objects_as_strings = 1;
CREATE TABLE test (id UInt64, obj String, date Date) ENGINE=Memory();
INSERT INTO test FORMAT JSONEachRow {"id" : 1, "obj" : {"a" : 1, "b" : "Hello"}, "date" : "2020-01-01"};
SELECT * FROM test;
```
结果：
```
┌─id─┬─obj──────────────────────┬───────date─┐
│ 1 │ {"a" : 1, "b" : "Hello"} │ 2020-01-01 │
└────┴──────────────────────────┴────────────┘
```
默认启用。
## input\_format\_json\_throw\_on\_bad\_escape\_sequence
如果 JSON 字符串在 JSON 输入格式中包含错误的转义序列，则抛出异常。如果禁用，错误的转义序列将按原样保留在数据中。
默认启用。
## input\_format\_json\_try\_infer\_named\_tuples\_from\_objects
如果启用，ClickHouse 会在进行 schema 推断时尝试从 JSON 对象中推断命名 Tuple。
生成的命名 Tuple 将包含样本数据中所有对应 JSON 对象里的全部元素。
示例：
```sql theme={null}
SET input_format_json_try_infer_named_tuples_from_objects = 1;
DESC format(JSONEachRow, '{"obj" : {"a" : 42, "b" : "Hello"}}, {"obj" : {"a" : 43, "c" : [1, 2, 3]}}, {"obj" : {"d" : {"e" : 42}}}')
```
结果：
```
┌─name─┬─type───────────────────────────────────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ obj │ Tuple(a Nullable(Int64), b Nullable(String), c Array(Nullable(Int64)), d Tuple(e Nullable(Int64))) │ │ │ │ │ │
└──────┴────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
```
默认启用。
## input\_format\_json\_try\_infer\_numbers\_from\_strings
如果启用，ClickHouse 在进行 schema 推断时会尝试从字符串字段中推断数值。
如果 JSON 数据中包含带引号的 UInt64 数值，此设置会很有用。
默认禁用。
## input\_format\_json\_use\_string\_type\_for\_ambiguous\_paths\_in\_named\_tuples\_inference\_from\_objects
在从 JSON 对象推断命名元组时，如果存在歧义路径，则使用 String 类型而不是抛出异常
## input\_format\_json\_validate\_types\_from\_metadata
对于 JSON/JSONCompact/JSONColumnsWithMetadata 输入格式，如果此设置设为 1，
则会将输入数据中元数据中的类型与表中对应列的类型进行比较。
默认启用。
## input\_format\_max\_block\_size\_bytes
限制输入格式在数据解析过程中形成的块大小 (以字节为单位) 。用于基于行的输入格式，且仅在块由 ClickHouse 端生成时生效。
0 表示不限制字节大小。
## input\_format\_max\_block\_wait\_ms
限制在基于行的输入 format 中，解析期间发出块前的最长等待时间 (以毫秒为单位) 。0 表示不限制。
该选项仅在启用 `input_format_connection_handling` 时生效。设置该值还会禁用并行解析，并导致无法去重。
对于流式 insert，你还必须设置 `min_insert_block_size_rows=0` 和 `min_insert_block_size_bytes=0`。否则，已解析的块仍可能在块 squashing 阶段累积在内存中，直到达到这些阈值，从而无法及时插入。
**Example：将 Wikipedia 的最近更改流式写入 ClickHouse**
```bash theme={null}
clickhouse-client --query 'CREATE TABLE wikipedia_edits (data JSON)'
curl -sS --globoff -H 'Accept: application/json' --no-buffer \
'https://stream.wikimedia.org/v2/stream/recentchange' \
| clickhouse-client \
--query 'INSERT INTO wikipedia_edits FORMAT JSONAsObject' \
--input_format_max_block_wait_ms 1000 \
--input_format_connection_handling 1 \
--min_insert_block_size_rows 0 \
--min_insert_block_size_bytes 0
```
## input\_format\_max\_bytes\_to\_read\_for\_schema\_inference
自动进行 schema 推断时可读取的最大数据量 (以字节为单位) 。
## input\_format\_max\_rows\_to\_read\_for\_schema\_inference
自动进行 schema 推断时，最多读取的数据行数。
## input\_format\_msgpack\_number\_of\_columns
插入的 MsgPack 数据中的列数。用于从数据中自动推断 schema。
## input\_format\_mysql\_dump\_map\_column\_names
按名称匹配 MySQL 转储中的表列与 ClickHouse 表中的列名
## input\_format\_mysql\_dump\_table\_name
从中读取数据的 MySQL 转储中的表名
## input\_format\_native\_allow\_types\_conversion
允许在 Native 输入格式中进行类型转换
## input\_format\_native\_decode\_types\_in\_binary\_format
在 Native 输入格式 中以二进制格式读取数据类型，而不是读取类型名称
## input\_format\_null\_as\_default
启用或禁用以下行为：当这些字段的数据类型不是 [Nullable](/zh/reference/data-types/nullable) 时，使用[默认值](/zh/reference/statements/create/table#default_values)初始化 [NULL](/zh/reference/syntax#literals) 字段。
如果列类型不是 Nullable 且此设置被禁用，则插入 `NULL` 会导致异常。如果列类型是 Nullable，则无论此设置如何，`NULL` 值都会按原样插入。
此设置适用于大多数输入格式。
对于复杂的默认表达式，还必须启用 `input_format_defaults_for_omitted_fields`。
可能的值：
* 0 — 将 `NULL` 插入非 Nullable 列会导致异常。
* 1 — `NULL` 字段将使用列的默认值进行初始化。
## input\_format\_orc\_allow\_missing\_columns
读取 ORC 输入格式时允许缺失列
## input\_format\_orc\_case\_insensitive\_column\_matching
匹配 ORC 列和 CH 列时忽略大小写。
## input\_format\_orc\_dictionary\_as\_low\_cardinality
读取 ORC 文件时，将采用 ORC 字典编码的列视为 LowCardinality 列。
## input\_format\_orc\_filter\_push\_down
读取 ORC 文件时，可根据 WHERE/PREWHERE 表达式、最小/最大统计信息或 ORC 元数据中的 bloom filter，跳过整个 stripe 或行组。
## input\_format\_orc\_reader\_time\_zone\_name
ORC 行读取器使用的时区名称，默认时区为 GMT。
## input\_format\_orc\_row\_batch\_size
读取 ORC 条带时的批次大小。
## input\_format\_orc\_skip\_columns\_with\_unsupported\_types\_in\_schema\_inference
在对 ORC 格式进行 schema 推断时，跳过类型不受支持的列
## input\_format\_orc\_use\_fast\_decoder
使用更快的 ORC 解码器实现版本。
## input\_format\_parallel\_parsing
启用或禁用在并行解析数据格式时保持顺序。仅支持 [TabSeparated (TSV)](/zh/reference/formats/TabSeparated/TabSeparated)、[TSKV](/zh/reference/formats/TabSeparated/TSKV)、[CSV](/zh/reference/formats/CSV/CSV) 和 [JSONEachRow](/zh/reference/formats/JSON/JSONEachRow) 格式。
可能的值：
* 1 — 启用。
* 0 — 禁用。
## input\_format\_parquet\_allow\_geoparquet\_parser
使用 geo 列解析器将 Array(UInt8) 转换为 Point/Linestring/Polygon/MultiLineString/MultiPolygon 类型
## input\_format\_parquet\_allow\_missing\_columns
读取 Parquet 输入格式时允许缺失列
## input\_format\_parquet\_bloom\_filter\_push\_down
读取 Parquet 文件时，会根据 WHERE 表达式以及 Parquet 元数据中的 bloom filter 跳过整个行组。
## input\_format\_parquet\_case\_insensitive\_column\_matching
在匹配 Parquet 列和 CH 列时忽略大小写。
## input\_format\_parquet\_enable\_json\_parsing
在读取 Parquet 文件时，将 JSON 列解析为 ClickHouse JSON 列。
## input\_format\_parquet\_enable\_row\_group\_prefetch
在解析 Parquet 时启用行组预取。目前仅单线程解析支持预取。
## input\_format\_parquet\_filter\_push\_down
读取 Parquet 文件时，可根据 WHERE/PREWHERE 表达式以及 Parquet 元数据中的最小值/最大值统计信息跳过整个行组。
## input\_format\_parquet\_local\_file\_min\_bytes\_for\_seek
在 Parquet 输入格式中，本地读取 (文件) 执行寻道而非忽略读取所需的最小字节数
## input\_format\_parquet\_local\_time\_as\_utc
确定在对 `isAdjustedToUTC=false` 的 Parquet 时间戳进行 schema inference 时使用的数据类型。如果为 true：DateTime64(..., 'UTC')；如果为 false：DateTime64(...)。这两种行为都不完全正确，因为 ClickHouse 没有表示本地挂钟时间的数据类型。虽然这有些违反直觉，但 `true` 可能是相对没那么错误的选项，因为将 `'UTC'` 时间戳格式化为 String 时，会得到正确的本地时间表示。
## input\_format\_parquet\_max\_block\_size
Parquet 读取器的最大块大小。
## input\_format\_parquet\_memory\_high\_watermark
Parquet reader v3 的近似内存上限。它会限制可并行读取的行组或列的数量。在一次查询中读取多个文件时，此限制针对这些文件的总内存使用量。
## input\_format\_parquet\_memory\_low\_watermark
如果内存使用量低于阈值，则会更积极地调度预取。例如，当需要通过网络读取大量小型布隆过滤器时，这项设置可能会很有用。
## input\_format\_parquet\_page\_filter\_push\_down
使用列索引中的最小值/最大值跳过数据页。
## input\_format\_parquet\_prefer\_block\_bytes
Parquet reader 输出的平均块大小 (字节)
## input\_format\_parquet\_preserve\_order
从 Parquet 文件读取时，避免重新排序行。不建议这样做，因为通常无法保证行顺序，而且查询管道的其他部分也可能打乱这种顺序。请改用 `ORDER BY _row_number`。
## input\_format\_parquet\_skip\_columns\_with\_unsupported\_types\_in\_schema\_inference
在对 Parquet 格式进行 schema 推断 时，跳过类型不受支持的列
## input\_format\_parquet\_use\_offset\_index
在未使用页面过滤器时，对 Parquet file 中页面的读取方式做了小幅调整。
## input\_format\_parquet\_verify\_checksums
在读取 Parquet 文件时验证页校验和。
## input\_format\_protobuf\_flatten\_google\_wrappers
为普通的非嵌套列启用 Google 包装器类型，例如，对 String 列 `str` 使用 google.protobuf.StringValue `str`。对于 Nullable 列，空包装器会被视为默认值，缺失的则会被视为 NULL
## input\_format\_protobuf\_oneof\_presence
通过在特殊列中设置枚举值，指示检测到的是 protobuf oneof 中的哪个字段
## input\_format\_protobuf\_skip\_fields\_with\_unsupported\_types\_in\_schema\_inference
在对 Protobuf 格式进行 schema 推断 时，跳过类型不受支持的字段
## input\_format\_record\_errors\_file\_path
读取文本格式 (CSV、TSV) 时用于记录错误的文件路径。
## input\_format\_skip\_unknown\_fields
启用或禁用在插入时跳过额外数据。
写入数据时，如果输入数据包含目标表中不存在的列，ClickHouse 会抛出异常。如果启用跳过，ClickHouse 将不会插入这些额外数据，也不会抛出异常。
支持的格式：
* [JSONEachRow](/zh/reference/formats/JSON/JSONEachRow) (以及其他 JSON 格式)
* [BSONEachRow](/zh/reference/formats/BSONEachRow) (以及其他 JSON 格式)
* [TSKV](/zh/reference/formats/TabSeparated/TSKV)
* 所有带有 WithNames/WithNamesAndTypes 后缀的格式
* [MySQLDump](/zh/reference/formats/MySQLDump)
* [Native](/zh/reference/formats/Native)
可能的值：
* 0 — 禁用。
* 1 — 启用。
## input\_format\_try\_infer\_dates
如果启用，ClickHouse 会在文本格式的 schema 推断 过程中，尝试从字符串字段中推断出 `Date` 类型。如果输入数据中某一列的所有字段都成功解析为日期，则结果类型为 `Date`；如果至少有一个字段未能解析为日期，则结果类型为 `String`。
默认启用。
## input\_format\_try\_infer\_datetimes
如果启用，ClickHouse 会在文本格式的 schema 推断 中尝试从字符串字段推断 `DateTime64` 类型。如果输入数据中某一列的所有字段都成功解析为日期时间，则结果类型为 `DateTime64`；如果其中至少有一个字段未能解析为日期时间，则结果类型为 `String`。
默认启用。
## input\_format\_try\_infer\_datetimes\_only\_datetime64
启用 input\_format\_try\_infer\_datetimes 时，仅推断 DateTime64，不推断 DateTime 类型
## input\_format\_try\_infer\_exponent\_floats
在文本格式中进行 schema 推断时，尝试推断以科学计数法表示的浮点数 (JSON 除外，其中这类数字始终会被推断)
## input\_format\_try\_infer\_integers
启用后，ClickHouse 会在文本格式的 schema 推断 中尽量将整数推断为整数类型，而不是浮点类型。如果输入数据中该列的所有数值都是整数，则结果类型为 `Int64`；如果至少有一个数值是浮点数，则结果类型为 `Float64`。
默认启用。
## input\_format\_try\_infer\_variants
如果启用，ClickHouse 会在文本格式的 schema 推断 中，当列/Array 元素存在多种可能类型时，尝试推断 [`Variant`](/zh/reference/data-types/variant) 类型。
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
## input\_format\_tsv\_allow\_variable\_number\_of\_columns
忽略 TSV 输入中的多余列 (如果文件中的列数超出预期) ，并将 TSV 输入中缺失的字段按默认值处理
## input\_format\_tsv\_crlf\_end\_of\_line
如果将其设为 true，file 函数将按 \r\n 而不是 \n 读取 TSV 格式。
自动检测 TSV 格式中包含列名和类型的表头
## input\_format\_tsv\_empty\_as\_default
将 TSV 输入中的空字段按默认值处理。
## input\_format\_tsv\_enum\_as\_number
将 TSV 格式中插入的枚举值按枚举索引处理。
## input\_format\_tsv\_skip\_first\_lines
跳过 TSV 格式数据开头的指定行数
## input\_format\_tsv\_skip\_trailing\_empty\_lines
跳过 TSV 格式末尾的空行
## input\_format\_tsv\_use\_best\_effort\_in\_schema\_inference
使用一些调整和启发式方法来推断 TSV 格式中的 schema
## input\_format\_values\_accurate\_types\_of\_literals
对于 Values 格式：在使用模板解析和解释表达式时，会检查字面量的实际类型，以避免可能出现的溢出和精度问题。
## input\_format\_values\_deduce\_templates\_of\_expressions
对于 Values 格式：如果字段无法通过流式解析器解析，则运行 SQL 解析器，推导出 SQL 表达式的模板，尝试使用该模板解析所有行，然后对所有行解释该表达式。
## input\_format\_values\_interpret\_expressions
对于 Values 格式：如果字段无法通过流式解析器解析，则运行 SQL 解析器，并尝试将其解释为 SQL 表达式。
启用或禁用在插入数据时检查列顺序。
为提高 insert 性能，如果你确定输入数据的列顺序与目标表一致，建议禁用此检查。
支持的格式：
* [CSVWithNames](/zh/reference/formats/CSV/CSVWithNames)
* [CSVWithNamesAndTypes](/zh/reference/formats/CSV/CSVWithNamesAndTypes)
* [TabSeparatedWithNames](/zh/reference/formats/TabSeparated/TabSeparatedWithNames)
* [TabSeparatedWithNamesAndTypes](/zh/reference/formats/TabSeparated/TabSeparatedWithNamesAndTypes)
* [JSONCompactEachRowWithNames](/zh/reference/formats/JSON/JSONCompactEachRowWithNames)
* [JSONCompactEachRowWithNamesAndTypes](/zh/reference/formats/JSON/JSONCompactEachRowWithNamesAndTypes)
* [JSONCompactStringsEachRowWithNames](/zh/reference/formats/JSON/JSONCompactStringsEachRowWithNames)
* [JSONCompactStringsEachRowWithNamesAndTypes](/zh/reference/formats/JSON/JSONCompactStringsEachRowWithNamesAndTypes)
* [RowBinaryWithNames](/zh/reference/formats/RowBinary/RowBinaryWithNames)
* [RowBinaryWithNamesAndTypes](/zh/reference/formats/RowBinary/RowBinaryWithNamesAndTypes)
* [CustomSeparatedWithNames](/zh/reference/formats/CustomSeparated/CustomSeparatedWithNames)
* [CustomSeparatedWithNamesAndTypes](/zh/reference/formats/CustomSeparated/CustomSeparatedWithNamesAndTypes)
可能的值：
* 0 — 禁用。
* 1 — 启用。
控制格式解析器是否检查输入数据中的数据类型是否与目标表中的数据类型一致。
支持的格式：
* [CSVWithNamesAndTypes](/zh/reference/formats/CSV/CSVWithNamesAndTypes)
* [TabSeparatedWithNamesAndTypes](/zh/reference/formats/TabSeparated/TabSeparatedWithNamesAndTypes)
* [JSONCompactEachRowWithNamesAndTypes](/zh/reference/formats/JSON/JSONCompactEachRowWithNamesAndTypes)
* [JSONCompactStringsEachRowWithNamesAndTypes](/zh/reference/formats/JSON/JSONCompactStringsEachRowWithNamesAndTypes)
* [RowBinaryWithNamesAndTypes](/zh/reference/formats/RowBinary/RowBinaryWithNamesAndTypes)
* [CustomSeparatedWithNamesAndTypes](/zh/reference/formats/CustomSeparated/CustomSeparatedWithNamesAndTypes)
可能的值：
* 0 — 已禁用。
* 1 — 已启用。
## insert\_distributed\_one\_random\_shard
在没有分布式键时，启用或禁用向 [Distributed](/zh/reference/engines/table-engines/special/distributed) 表随机插入某个分片。
默认情况下，向包含多个分片的 `Distributed` 表插入数据时，如果没有分布式键，ClickHouse 服务器会拒绝任何插入请求。当 `insert_distributed_one_random_shard = 1` 时，则允许插入，数据会被随机转发到所有分片中的某一个。
可能的值：
* 0 — 如果存在多个分片且未提供分布式键，则拒绝插入。
* 1 — 如果未提供分布式键，则在所有可用分片中随机选择一个执行插入。
## interval\_output\_format
允许为时间间隔类型的文本表示选择不同的输出格式。
可能的值：
* `kusto` - KQL 风格输出格式。
ClickHouse 以 [KQL 格式](https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-timespan-format-strings#the-constant-c-format-specifier)输出时间间隔。例如，`toIntervalDay(2)` 会格式化为 `2.00:00:00`。请注意，对于长度可变的时间间隔类型 (即 `IntervalMonth` 和 `IntervalYear`) ，会按每个时间间隔的平均秒数进行换算。
* `numeric` - 数值输出格式。
ClickHouse 将时间间隔输出为其底层数值表示。例如，`toIntervalDay(2)` 会格式化为 `2`。
另请参阅：
* [Interval](/zh/reference/data-types/special-data-types/interval)
## into\_outfile\_create\_parent\_directories
使用 INTO OUTFILE 时，如果父目录不存在，则自动创建父目录。
## json\_type\_escape\_dots\_in\_keys
启用后，在解析 JSON 时会转义键中的点号。
## max\_dynamic\_subcolumns\_in\_json\_type\_parsing
在解析 JSON 列时，每个列中可创建的动态子列的最大数量。
它可在解析期间控制动态子列的数量，而不受数据类型中指定的动态参数限制。
## output\_format\_arrow\_compression\_method
Arrow 输出格式的压缩方法。支持的编解码器：lz4\_frame、zstd、none (未压缩) 。
## output\_format\_arrow\_date\_as\_uint16
将 Date 值写为普通的 16 位数字 (读取时为 UInt16) ，而不是转换为 32 位的 Arrow DATE32 类型 (读取时为 Date32) 。
## output\_format\_arrow\_fixed\_string\_as\_fixed\_byte\_array
对 FixedString 列，使用 Arrow FIXED\_SIZE\_BINARY 类型而不是 Binary。
## output\_format\_arrow\_low\_cardinality\_as\_dictionary
启用将 LowCardinality 类型以 Arrow 的 Dictionary 类型输出
## output\_format\_arrow\_string\_as\_string
对 String 列使用 Arrow String 类型，而不是 Binary
## output\_format\_arrow\_unsupported\_types\_as\_binary
将无法转换的输出类型以原始二进制数据形式输出。如果为 false，则此类类型会抛出 UNKNOWN\_TYPE 异常。
## output\_format\_arrow\_use\_64\_bit\_indexes\_for\_dictionary
在 Arrow 格式中始终对字典索引使用 64 位整数
## output\_format\_arrow\_use\_signed\_indexes\_for\_dictionary
在 Arrow 格式 中对字典索引使用有符号整数
## output\_format\_avro\_codec
用于输出的压缩编解码器。可能的值：'null'、'deflate'、'snappy'、'zstd'。
## output\_format\_avro\_confluent\_subject
对于 AvroConfluent 输出格式：schema 在 Confluent Schema Registry 中注册时使用的 subject 名称。写入 AvroConfluent 输出时必需。
## output\_format\_avro\_rows\_in\_file
单个文件中的最大行数 (如果存储支持)
## output\_format\_avro\_string\_column\_pattern
对于 Avro 格式：用于选择要作为 AVRO 字符串输出的 String 类型列的正则表达式。
## output\_format\_avro\_sync\_interval
同步间隔 (以字节为单位) 。
## output\_format\_binary\_encode\_types\_in\_binary\_format
在 RowBinaryWithNamesAndTypes 输出格式中，以二进制格式写入数据类型，而不是类型名称
## output\_format\_binary\_write\_json\_as\_string
在 RowBinary 输出格式中，将 [JSON](/zh/reference/data-types/newjson) Data type 的值写为 JSON [String](/zh/reference/data-types/string) 值。
## output\_format\_bson\_string\_as\_string
对于 String 列，使用 BSON String 类型而非 Binary。
## output\_format\_compression\_level
当查询输出启用压缩时，使用的默认压缩级别。该设置会在 `SELECT` 查询包含 `INTO OUTFILE`，或写入表函数 `file`、`url`、`hdfs`、`s3` 或 `azureBlobStorage` 时生效。
可能的值：`1` 到 `22`
## output\_format\_compression\_zstd\_window\_log
可在输出压缩方法为 `zstd` 时使用。如果该值大于 `0`，此设置会显式指定压缩窗口大小 (`2` 的幂) ，并为 zstd 压缩启用长距离模式。这有助于获得更高的压缩率。
可能的值：非负数。请注意，如果该值过小或过大，`zstdlib` 会抛出异常。典型值范围为 `20` (窗口大小 = `1MB`) 到 `30` (窗口大小 = `1GB`) 。
## output\_format\_csv\_crlf\_end\_of\_line
如果将其设为 true，CSV 格式中的行尾将使用 \r\n 而不是 \n。
## output\_format\_csv\_serialize\_tuple\_into\_separate\_columns
如果将其设置为 true，则 CSV 格式中的 Tuple 会序列化为单独的列 (即会丢失其在 Tuple 中的嵌套结构)
## output\_format\_decimal\_trailing\_zeros
打印 Decimal 值时输出末尾的零。例如，输出 1.230000 而不是 1.23。
默认禁用。
## output\_format\_json\_array\_of\_rows
启用后，可在 [JSONEachRow](/zh/reference/formats/JSON/JSONEachRow) 格式中将所有行输出为一个 JSON 数组。
可能的值：
* 1 — ClickHouse 将所有行作为一个数组输出，其中每一行都采用 `JSONEachRow` 格式。
* 0 — ClickHouse 将每一行分别以 `JSONEachRow` 格式输出。
**启用该设置的查询示例**
查询：
```sql theme={null}
SET output_format_json_array_of_rows = 1;
SELECT number FROM numbers(3) FORMAT JSONEachRow;
```
结果：
```text theme={null}
[
{"number":"0"},
{"number":"1"},
{"number":"2"}
]
```
**禁用该设置后的查询示例**
查询：
```sql theme={null}
SET output_format_json_array_of_rows = 0;
SELECT number FROM numbers(3) FORMAT JSONEachRow;
```
结果：
```text theme={null}
{"number":"0"}
{"number":"1"}
{"number":"2"}
```
## output\_format\_json\_escape\_forward\_slashes
控制在 JSON 输出格式中，是否对字符串输出中的正斜杠进行转义。这是出于与 JavaScript 兼容的考虑。不要将其与始终会被转义的反斜杠混淆。
默认启用。
## output\_format\_json\_map\_as\_array\_of\_tuples
将 Map 列序列化为由 Tuple 构成的 JSON 数组。
默认禁用。
## output\_format\_json\_named\_tuples\_as\_objects
将命名元组列序列化为 JSON 对象。
默认启用。
## output\_format\_json\_pretty\_print
此设置决定了在使用 JSON 输出格式时，Tuple、Map 和 Array 等嵌套结构在 `data` 数组中的显示方式。
例如，不会输出成：
```json theme={null}
"data":
[
{
"tuple": {"a":1,"b":2,"c":3},
"array": [1,2,3],
"map": {"a":1,"b":2,"c":3}
}
],
```
输出格式如下：
```json theme={null}
"data":
[
{
"tuple": {
"a": 1,
"b": 2,
"c": 3
},
"array": [
1,
2,
3
],
"map": {
"a": 1,
"b": 2,
"c": 3
}
}
],
```
默认启用。
## output\_format\_json\_quote\_64bit\_floats
控制在 JSON\* 格式中输出 64 位 [floats](/zh/reference/data-types/float) 时，是否为其加上引号。
默认禁用。
## output\_format\_json\_quote\_64bit\_integers
控制在 [JSON](/zh/reference/formats/JSON/JSON) 格式中输出 64 位或更大的[整数](/zh/reference/data-types/int-uint) (如 `UInt64` 或 `Int128`) 时是否加引号。
默认情况下，这类整数会用引号括起来。这种行为与大多数 JavaScript 实现兼容。
可能的值：
* 0 — 整数输出时不加引号。
* 1 — 整数会用引号括起来。
## output\_format\_json\_quote\_decimals
控制在 JSON 输出格式中是否为 Decimal 值添加引号。
默认处于禁用状态。
## output\_format\_json\_quote\_denormals
在 [JSON](/zh/reference/formats/JSON/JSON) 输出格式中，允许输出 `+nan`、`-nan`、`+inf` 和 `-inf`。
可能的值：
* 0 — 禁用。
* 1 — 启用。
**示例**
考虑以下表 `account_orders`：
```text theme={null}
┌─id─┬─name───┬─duration─┬─period─┬─area─┐
│ 1 │ Andrew │ 20 │ 0 │ 400 │
│ 2 │ John │ 40 │ 0 │ 0 │
│ 3 │ Bob │ 15 │ 0 │ -100 │
└────┴────────┴──────────┴────────┴──────┘
```
当 `output_format_json_quote_denormals = 0` 时，查询输出中会返回 `null` 值：
```sql theme={null}
SELECT area/period FROM account_orders FORMAT JSON;
```
```json theme={null}
{
"meta":
[
{
"name": "divide(area, period)",
"type": "Float64"
}
],
"data":
[
{
"divide(area, period)": null
},
{
"divide(area, period)": null
},
{
"divide(area, period)": null
}
],
"rows": 3,
"statistics":
{
"elapsed": 0.003648093,
"rows_read": 3,
"bytes_read": 24
}
}
```
当 `output_format_json_quote_denormals = 1` 时，查询结果为：
```json theme={null}
{
"meta":
[
{
"name": "divide(area, period)",
"type": "Float64"
}
],
"data":
[
{
"divide(area, period)": "inf"
},
{
"divide(area, period)": "-nan"
},
{
"divide(area, period)": "-inf"
}
],
"rows": 3,
"statistics":
{
"elapsed": 0.000070241,
"rows_read": 3,
"bytes_read": 24
}
}
```
## output\_format\_json\_skip\_null\_value\_in\_named\_tuples
将命名元组列序列化为 JSON 对象时，跳过值为 null 的键值对。仅当 output\_format\_json\_named\_tuples\_as\_objects 为 true 时，此设置才生效。
## output\_format\_json\_validate\_utf8
控制是否在 JSON 输出格式中校验 UTF-8 序列；不影响 JSON/JSONCompact/JSONColumnsWithMetadata 格式，因为它们始终会校验 UTF-8。
默认禁用。
## output\_format\_markdown\_escape\_special\_characters
启用后，会对 Markdown 中的特殊字符进行转义。
[Common Mark](https://spec.commonmark.org/0.30/#example-12) 定义了以下可通过 : 进行转义的特殊字符：
```
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
```
可选值：
* 0 — 禁用。
* 1 — 启用。
## output\_format\_msgpack\_uuid\_representation
用于指定以 MsgPack 格式输出 UUID 的方式。
## output\_format\_native\_encode\_types\_in\_binary\_format
在 Native 输出格式中，以二进制格式写入数据类型，而不是写入类型名称
## output\_format\_native\_use\_flattened\_dynamic\_and\_json\_serialization
以扁平化格式写入 [JSON](/zh/reference/data-types/newjson) 和 [Dynamic](/zh/reference/data-types/dynamic) 列的数据 (将所有类型/路径作为单独的子列) 。
## output\_format\_native\_write\_json\_as\_string
将 [JSON](/zh/reference/data-types/newjson) 列写为包含 JSON 字符串的 [String](/zh/reference/data-types/string) 列，而不是使用默认的原生 JSON 序列化格式。
## output\_format\_orc\_compression\_block\_size
ORC 输出格式中压缩块的大小，单位为字节。
## output\_format\_orc\_compression\_method
ORC 输出格式的压缩方法。支持的编解码器：lz4、snappy、zlib、zstd、none (不压缩)
## output\_format\_orc\_dictionary\_key\_size\_threshold
对于 ORC 输出格式中的字符串列，如果不同值的数量大于非 NULL 行总数的这一比例，则关闭字典编码。否则启用字典编码
## output\_format\_orc\_row\_index\_stride
ORC 输出格式的目标行索引步长
## output\_format\_orc\_string\_as\_string
对 String 列使用 ORC String 类型，而不是 Binary
## output\_format\_orc\_writer\_time\_zone\_name
ORC 写入器使用的时区名称，默认时区为 GMT。
## output\_format\_parallel\_formatting
启用或禁用数据的并行格式化。仅支持 [TSV](/zh/reference/formats/TabSeparated/TabSeparated)、[TSKV](/zh/reference/formats/TabSeparated/TSKV)、[CSV](/zh/reference/formats/CSV/CSV) 和 [JSONEachRow](/zh/reference/formats/JSON/JSONEachRow) 格式。
可能的值：
* 1 — 启用。
* 0 — 禁用。
## output\_format\_parquet\_batch\_size
每处理这么多行就检查一次页大小。如果列中值的平均大小超过几 KB，建议适当调低此值。
## output\_format\_parquet\_bloom\_filter\_bits\_per\_value
Parquet 布隆过滤器中每个不同值使用的近似位数。估计的误报率如下：
* 6 位 - 10%
* 10.5 位 - 1%
* 16.9 位 - 0.1%
* 26.4 位 - 0.01%
* 41 位 - 0.001%
## output\_format\_parquet\_bloom\_filter\_flush\_threshold\_bytes
控制在 Parquet 文件中的何处写入布隆过滤器。布隆过滤器将按大致为该大小的分组写入。具体来说：
* 如果为 0，则每个行组的布隆过滤器都会在该行组之后立即写入，
* 如果大于所有布隆过滤器的总大小，则所有行组的布隆过滤器会先在内存中累积，然后在接近文件末尾处一起写入，
* 否则，布隆过滤器会先在内存中累积，并在其总大小超过该值时写出。
## output\_format\_parquet\_compression\_method
Parquet 输出格式的压缩方法。支持的编解码器：snappy、lz4、brotli、zstd、gzip、none (未压缩)
## output\_format\_parquet\_data\_page\_size
压缩前的目标页面大小 (以字节为单位) 。
## output\_format\_parquet\_date\_as\_uint16
将 Date 值写为普通的 16 位数值 (读回时为 UInt16) ，而不是转换为 32 位 Parquet DATE 类型 (读回时为 Date32) 。
## output\_format\_parquet\_datetime\_as\_uint32
将 DateTime 值写为原始 Unix 时间戳 (读取时为 UInt32) ，而不是转换为毫秒 (读取时为 DateTime64(3)) 。
## output\_format\_parquet\_enum\_as\_byte\_array
使用 Parquet 物理类型 BYTE\_ARRAY 和逻辑类型 ENUM 写入枚举
## output\_format\_parquet\_fixed\_string\_as\_fixed\_byte\_array
对于 FixedString 列，使用 Parquet FIXED\_LEN\_BYTE\_ARRAY 类型，而不是 Binary。
## output\_format\_parquet\_geometadata
允许将 Geo 列信息写入 Parquet 元数据，并将列编码为 WKB 格式。
## output\_format\_parquet\_max\_dictionary\_size
如果字典大小超过此字节数，将切换为不使用字典的编码。设置为 0 可禁用字典编码。
## output\_format\_parquet\_parallel\_encoding
使用多个线程进行 Parquet 编码。
## output\_format\_parquet\_row\_group\_size
目标行组大小 (按行数计) 。
## output\_format\_parquet\_row\_group\_size\_bytes
压缩前的目标行组大小，单位为字节。
## output\_format\_parquet\_string\_as\_string
对 String 列使用 Parquet String 类型，而不是 Binary。
## output\_format\_parquet\_write\_bloom\_filter
在 Parquet 文件中写入布隆过滤器。
## output\_format\_parquet\_write\_checksums
在 Parquet 页面头部中写入 crc32 校验和。
## output\_format\_parquet\_write\_page\_index
将列索引和偏移索引 (即每个数据页的统计信息，读取时可用于过滤器下推) 写入 Parquet 文件。
## output\_format\_pretty\_color
在 Pretty 格式中使用 ANSI 转义序列。0 - 禁用，1 - 启用，'auto' - 如果输出到终端则启用。
## output\_format\_pretty\_display\_footer\_column\_names
当表中的行数较多时，在页脚显示列名。
可能的值：
* 0 — 不在页脚显示列名。
* 1 — 当行数大于或等于 [output\_format\_pretty\_display\_footer\_column\_names\_min\_rows](#output_format_pretty_display_footer_column_names_min_rows) 设置的阈值时，在页脚显示列名 (默认值为 50) 。
**示例**
查询：
```sql theme={null}
SELECT *, toTypeName(*) FROM (SELECT * FROM system.numbers LIMIT 1000);
```
结果：
```response theme={null}
┌─number─┬─toTypeName(number)─┐
1. │ 0 │ UInt64 │
2. │ 1 │ UInt64 │
3. │ 2 │ UInt64 │
...
999. │ 998 │ UInt64 │
1000. │ 999 │ UInt64 │
└─number─┴─toTypeName(number)─┘
```
## output\_format\_pretty\_display\_footer\_column\_names\_min\_rows
如果启用了 [output\_format\_pretty\_display\_footer\_column\_names](#output_format_pretty_display_footer_column_names)，则此设置用于指定显示带列名页脚所需的最小行数。
## output\_format\_pretty\_fallback\_to\_vertical
如果启用，且表很宽但行数较少，Pretty 格式将按 Vertical 格式的方式输出。
有关此行为的详细调优，请参见 `output_format_pretty_fallback_to_vertical_max_rows_per_chunk` 和 `output_format_pretty_fallback_to_vertical_min_table_width`。
## output\_format\_pretty\_fallback\_to\_vertical\_max\_rows\_per\_chunk
仅当一个 chunk 中的记录数不超过指定值时，回退到 Vertical 格式 (参见 `output_format_pretty_fallback_to_vertical`) 才会生效。
## output\_format\_pretty\_fallback\_to\_vertical\_min\_columns
只有当列数大于指定值时，才会启用回退到 Vertical 格式 (参见 `output_format_pretty_fallback_to_vertical`) 。
## output\_format\_pretty\_fallback\_to\_vertical\_min\_table\_width
只有在表中各列长度总和至少达到指定值，或至少有一个值包含换行符时，才会启用回退到 Vertical 格式 (参见 `output_format_pretty_fallback_to_vertical`) 。
## output\_format\_pretty\_glue\_chunks
如果以 Pretty 格式渲染的数据分多个块到达，即使块之间存在延迟，只要下一个块的列宽与前一个块相同，就会使用 ANSI 转义序列回到上一行并覆盖前一个块的页脚，将新块的数据接续显示上去。这样可以让结果在视觉上更美观。
0 - 已禁用，1 - 已启用，'auto' - 在终端中时启用。
## output\_format\_pretty\_grid\_charset
用于输出网格边框的字符集。可用字符集：ASCII、UTF-8 (默认) 。
## output\_format\_pretty\_highlight\_digit\_groups
如果启用且输出到终端，则会以下划线高亮千位、百万位等对应的每一位数字。
## output\_format\_pretty\_highlight\_trailing\_spaces
如果已启用，且输出到终端时，则会以灰色并加下划线的方式高亮显示行尾空格。
## output\_format\_pretty\_max\_column\_name\_width\_cut\_to
如果列名过长，则将其截断到此长度。
如果列名长度超过 `output_format_pretty_max_column_name_width_cut_to` 与 `output_format_pretty_max_column_name_width_min_chars_to_cut` 之和，则会被截断。
## output\_format\_pretty\_max\_column\_name\_width\_min\_chars\_to\_cut
列名过长时，最少截断的字符数。
如果列名长度超过 `output_format_pretty_max_column_name_width_cut_to` 与 `output_format_pretty_max_column_name_width_min_chars_to_cut` 之和，则会被截断。
## output\_format\_pretty\_max\_column\_pad\_width
Pretty 格式 中单列内所有值的最大填充宽度。
## output\_format\_pretty\_max\_rows
Pretty 格式 的最大行数限制。
## output\_format\_pretty\_max\_value\_width
在 Pretty 格式中显示的值的最大宽度。如果超过该宽度，将被截断。
值为 0 表示永不截断。
## output\_format\_pretty\_max\_value\_width\_apply\_for\_single\_value
仅当某个值不是块中的单个值时，才会将其截断 (参见 `output_format_pretty_max_value_width` 设置) 。否则将完整输出，这对 `SHOW CREATE TABLE` 查询很有用。
## output\_format\_pretty\_multiline\_fields
如果启用，Pretty 格式会在表单元内以多行形式渲染字段，从而保持表格轮廓完整。
如果不启用，则会按原样渲染，这可能导致表格变形 (不过保持关闭的一个好处是，复制粘贴多行值会更方便) 。
## output\_format\_pretty\_named\_tuples\_as\_json
控制 Pretty 格式中的命名元组是否以美化格式的 JSON 对象输出。
## output\_format\_pretty\_row\_numbers
在 Pretty 输出格式中，为每一行添加行号
## output\_format\_pretty\_single\_large\_number\_tip\_threshold
如果块仅包含一个超过此值的数值 (0 除外) ，则在表右侧显示易读的数值提示
## output\_format\_pretty\_squash\_consecutive\_ms
写入前，最多等待指定毫秒数以接收下一个块，并在写入前将其合并到前一个块中。
这样既可避免过于频繁地输出过小的块，又仍能以流式方式显示数据。
## output\_format\_pretty\_squash\_max\_wait\_ms
如果距离上一次输出已经超过指定的毫秒数，则将待处理的块以 Pretty 格式输出。
## output\_format\_protobuf\_nullables\_with\_google\_wrappers
使用 Google wrappers 序列化 Nullable 列时，会将默认值序列化为空的 wrappers。关闭后，默认值和 NULL 值都不会被序列化
## output\_format\_schema
用于保存自动生成 schema 的文件路径，格式为 [Cap'n Proto](/zh/reference/formats/CapnProto) 或 [Protobuf](/zh/reference/formats/Protobuf/Protobuf)。
## output\_format\_sql\_insert\_include\_column\_names
在 INSERT 查询中包含列名
## output\_format\_sql\_insert\_max\_batch\_size
单条 INSERT 语句中的最大行数。
## output\_format\_sql\_insert\_quote\_names
使用 '\`' 字符为列名加引号
## output\_format\_sql\_insert\_table\_name
输出 INSERT 查询中表的名称
## output\_format\_sql\_insert\_use\_replace
使用 REPLACE 语句，而非 INSERT
## output\_format\_trim\_fixed\_string
在文本输出格式中，裁剪 FixedString 值末尾的零字节。例如，`toFixedString('John', 8)` 会输出为 `John`，而不是 `John\0\0\0\0`。
## output\_format\_tsv\_crlf\_end\_of\_line
如果设置为 true，TSV 格式的行尾将使用 \r\n，而不是 \n。
## output\_format\_values\_escape\_quote\_with\_quote
如果为 true，则将 ' 转义为 ''；否则使用 \\' 进行引用
## output\_format\_write\_statistics
在适用的输出格式中写入有关已读取行数、字节数和耗时的统计信息。
默认启用
## precise\_float\_parsing
优先采用更精确 (但速度更慢) 的浮点数解析算法
## schema\_inference\_hints
在无 schema 的格式中，用作 schema 推断提示的列名和类型列表。
示例：
查询：
```sql theme={null}
desc format(JSONEachRow, '{"x" : 1, "y" : "String", "z" : "0.0.0.0" }') settings schema_inference_hints='x UInt8, z IPv4';
```
结果：
```sql theme={null}
x UInt8
y Nullable(String)
z IPv4
```
如果 `schema_inference_hints` 的格式不正确，或者存在拼写错误、数据类型错误等问题……整个 `schema_inference_hints` 都会被忽略。
## schema\_inference\_make\_columns\_nullable
控制在 schema 推断 中是否将推断出的类型设为 `Nullable`。
Possible values:
* 0 - 推断出的类型绝不会为 `Nullable` (这种情况下如何处理 null 值，可使用 input\_format\_null\_as\_default 控制) ，
* 1 - 所有推断出的类型都会是 `Nullable`，
* 2 or `auto` - 仅当某列在 schema 推断 期间解析的样本中包含 `NULL`，或文件元数据中包含该列可空性的信息时，推断出的类型才会是 `Nullable`，
* 3 - 如果该 format 提供文件元数据中的可空性信息 (例如 Parquet) ，则推断出的类型可空性将与之保持一致；否则始终为 `Nullable` (例如 CSV) 。
## schema\_inference\_make\_json\_columns\_nullable
控制在 schema 推断 中将推断出的 JSON type 设为 `Nullable`。
如果此设置与 schema\_inference\_make\_columns\_nullable 同时启用，则推断出的 JSON type 将为 `Nullable`。
## schema\_inference\_mode
schema 推断 模式。'default' - 假定所有文件都具有相同的 schema，且可从任意文件推断出 schema；'union' - 文件可以具有不同的 schema，最终得到的 schema 应为所有文件 schema 的并集
## show\_create\_query\_identifier\_quoting\_rule
设置 SHOW CREATE 查询中标识符的引号使用规则
## show\_create\_query\_identifier\_quoting\_style
设置 SHOW CREATE 查询中标识符的引号样式
## type\_json\_allow\_duplicated\_key\_with\_literal\_and\_nested\_object
启用后，允许解析如下 JSON：某个键重复出现，但其中一个值为嵌套对象，例如 `{"a" : 42, "a" : {"b" : 42}}`。
## type\_json\_skip\_duplicated\_paths
启用后，在将 JSON object 解析为 JSON type 时，重复的 paths 会被忽略，只会插入第一个，而不会抛出异常
## type\_json\_skip\_invalid\_typed\_paths
启用后，对于带有类型化路径的 JSON type 列，如果某个字段的值无法转换为其声明的类型，则会跳过该字段，而不是抛出错误。被跳过的字段会视为缺失，并根据类型化路径的定义使用默认值/NULL 值。
此设置仅适用于 JSON type 列 (例如 `JSON(a Int64, b String)`) ，即某些特定路径已声明类型的情况。它不适用于常规的 JSON input formats，例如将数据插入普通类型化列时使用的 `JSONEachRow`。
Possible values:
* 0 — 禁用 (类型不匹配时抛出错误) 。
* 1 — 启用 (类型不匹配时跳过字段) 。
## type\_json\_use\_partial\_match\_to\_skip\_paths\_by\_regexp
启用后，在将 JSON object 解析为 JSON type 时，使用 SKIP REGEXP 指定的 regular expression 只要部分匹配即可跳过某个 path。禁用后，则必须完全匹配。
## validate\_experimental\_and\_suspicious\_types\_inside\_nested\_types
验证是否在 Array/Map/Tuple 等嵌套类型内部使用 Experimental 和可疑类型