这些设置是根据源文件自动生成的。
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
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.12 | 1 | 默认允许 Arrow 文件缺失列 |
读取 Arrow 输入格式时允许缺失列
input_format_arrow_case_insensitive_column_matching
匹配 Arrow 列与 CH 列时忽略大小写。
input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference
在对 Arrow 格式进行 schema 推断 时,跳过类型不受支持的列
input_format_avro_allow_missing_fields
对于 Avro/AvroConfluent format:当在 schema 中找不到 字段 时,使用默认值而不是报错
input_format_avro_null_as_default
对于 Avro/AvroConfluent 格式:当值为 NULL 且列为非 Nullable 时,插入默认值
input_format_binary_decode_types_in_binary_format
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.7 | 0 | 新增此设置,以允许在 RowBinaryWithNamesAndTypes 输入格式中以二进制格式读取类型名称 |
在 RowBinaryWithNamesAndTypes 输入格式中,以二进制格式读取数据类型,而不是类型名称
input_format_binary_max_type_complexity
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.1 | 1000 | 新增一个设置,用于控制解码二进制类型时允许的最大类型节点数。可防止恶意输入。 |
解码二进制类型时允许的最大类型节点数 (不是深度,而是节点总数) 。Map(String, UInt32) = 3 个节点。可防止恶意输入。0 = 不限制。
input_format_binary_read_json_as_string
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.10 | 0 | 新增设置,用于在 RowBinary 输入格式中将 JSON 类型的值读取为 JSON 字符串 |
在 RowBinary 输入格式中,将 JSON 数据类型的值读取为 JSON String 值。
input_format_bson_skip_fields_with_unsupported_types_in_schema_inference
在对 BSON format 进行 schema 推断 时,跳过具有不受支持类型的字段。
input_format_capn_proto_skip_fields_with_unsupported_types_in_schema_inference
在对 CapnProto 格式进行 schema 推断时,跳过类型不受支持的列
input_format_column_name_matching_mode
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.5 | auto | 先按区分大小写的方式匹配输入列名,若失败则回退为不区分大小写的匹配,而不是要求大小写必须完全一致。 |
| 26.4 | match_case | 新设置。 |
定义通过各种格式 (包括但不限于 JSONEachRow、CSVWithNames、JSONColumns、BSONEachRow、RowBinaryWithNames) 摄取数据时的列名匹配模式。 支持的模式:
- match_case:区分大小写匹配
- ignore_case:不区分大小写匹配
- auto:先尝试区分大小写匹配;如果失败,再尝试不区分大小写匹配。
input_format_connection_handling
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.2 | 0 | 新增设置:允许在连接意外关闭时,对缓冲区中的剩余数据继续进行解析和处理 |
启用此选项后,如果连接意外关闭,缓冲区中的剩余数据将被解析和处理,而不会被视为错误
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
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.6 | 1 | 新增了一种在 CSV 格式中解析 Tuple 的方式。 |
| 24.3 | 1 | 新增了一种在 CSV 格式中解析 Tuple 的方式。 |
如果将其设置为 true,则可以将以 CSV 格式写入的独立列反序列化为 Tuple 列。
这仅适用于裸 Tuple。Nullable(Tuple) 始终会被写为单个 CSV 字段 (参见 output_format_csv_serialize_tuple_into_separate_columns) ,并且也始终从单个字段读回,而不会从独立列中读取,无论此设置如何。Nullable(Tuple) 不支持按独立列解析,因为前导 \N 字段存在歧义 (它既可能表示元组外层的 NULL,也可能表示其第一个元素的 NULL) 。
由于裸 Tuple 的每个元素各占一个字段,直接顶层元素字段中的 \N 表示该元素,而非整个列,因此 input_format_null_as_default 会应用于该元素。若一行仅为整个元组提供单个字段,则会缺少其余元素的字段,并会被拒绝,而不会采用列默认值。将此设置设为 0,可再次将此类字段作为整个列读取。嵌套 Tuple 元素字段中的 \N 仍会被读取为整个嵌套元素。
input_format_csv_detect_header
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.1 | 1 | 默认检测 CSV 格式中的名称和类型请求头 |
自动检测 CSV 格式中的名称和类型请求头
input_format_csv_empty_as_default
将 CSV 输入中的空字段按默认值处理。
input_format_csv_enum_as_number
将 CSV 格式中插入的枚举值视为枚举索引
input_format_csv_missing_nullable_as_empty_string
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.7 | 0 | 新增设置:将 CSV 中 `Nullable(String)` 的缺失值读取为空字符串,而不是 NULL。 |
控制如何将 CSV 中的缺失值读取为 Nullable(String)。缺失值是指逗号之间、之前或之后未被引号包围的空白内容。如果启用此设置,则无论 input_format_csv_empty_as_default 的值为何,Nullable(String) 的缺失值都会被解释为空 String,而不是 NULL。
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
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.6 | 1 | 新增了一种在 CSV 格式中解释 Tuple 的方式。 |
| 24.3 | 1 | 新增了一种在 CSV 格式中解释 Tuple 的方式。 |
将输入数据中带引号的 Tuple 解释为 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 输入中缺失的字段视为默认值
input_format_custom_detect_header
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.1 | 1 | 默认检测 CustomSeparated format 中包含名称和类型的请求头 |
自动检测 CustomSeparated format 中包含名称和类型的请求头
input_format_custom_skip_trailing_empty_lines
跳过 CustomSeparated format 末尾的空行
input_format_defaults_for_omitted_fields
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 19.12 | 1 | 对某些输入格式,为省略字段启用复杂默认表达式的计算,因为这才是符合预期的行为 |
执行 INSERT 查询时,将省略的输入列值替换为对应列的默认值。此选项适用于 JSONEachRow (以及其他 JSON 格式) 、CSV、TabSeparated、TSKV、Parquet、Arrow、Avro、ORC、Native 格式,以及带有 WithNames/WithNamesAndTypes 后缀的格式。
可能的值:
- 0 — 禁用。
- 1 — 启用。
input_format_force_null_for_omitted_fields
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.5 | 0 | 在需要时禁用被省略字段的类型默认值 |
强制将被省略的字段初始化为 NULL 值
input_format_geojson_unsupported_geometry_handling
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.6 | throw | 新增设置,用于控制对无法用 `Geometry` 类型表示的 GeoJSON geometry types(例如 `GeometryCollection`)的处理方式 |
控制在读取 GeoJSON 输入时,如果需要将一种无法在 ClickHouse 的 Geometry 类型中表示的有效 GeoJSON 几何类型 (如 GeometryCollection) 存储到 geometry 列中时,系统的处理方式。
可能的值:
'throw'(默认) — 抛出异常。'null'— 为geometry列插入NULL值并继续解析。
这仅在 geometry 列被 materialized 时适用。当它不是请求的输出列时,此类几何对象只会验证其格式是否正确,但不会触发该处理。
input_format_hive_text_allow_variable_number_of_columns
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.4 | 1 | 忽略 Hive Text 输入中的多余列(如果文件中的列数超出预期),并将 Hive Text 输入中缺失的字段视为默认值。 |
忽略 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 数据。
支持的格式:
可能的值:
- 0 — 禁用。
- 1 — 启用。
另请参阅:
- Nested 结构的用法 (使用
JSONEachRow格式) 。
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
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.1 | 1 | 默认允许在读取命名元组时,JSON 对象中缺失元素 |
在解析命名元组时,会为 JSON 对象中缺失的元素插入默认值。
此设置仅在启用 input_format_json_named_tuples_as_objects 时生效。
默认启用。
input_format_json_empty_as_default
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.9 | 0 | 新增设置,允许将 JSON 输入中的空字段按默认值处理。 |
启用后,会将 JSON 输入中的空字段替换为默认值。对于复杂的默认表达式,还必须同时启用 input_format_defaults_for_omitted_fields。
可能的值:
- 0 — 禁用。
- 1 — 启用。
input_format_json_ignore_unknown_keys_in_named_tuple
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.3 | 1 | 改进将 JSON 对象解析为命名元组 |
忽略用于命名元组的 JSON 对象中的未知键。
默认启用。
input_format_json_ignore_unnecessary_fields
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.4 | 1 | 忽略不必要的字段,并且不解析它们。启用后,对于格式无效或包含重复字段的 JSON 字符串,可能不会抛出异常 |
忽略不必要的字段,并且不解析它们。启用后,对于格式无效或包含重复字段的 JSON 字符串,可能不会抛出异常
input_format_json_infer_array_of_dynamic_from_array_of_different_types
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.8 | 1 | 默认将值类型不同的 JSON 数组推断为 Array(Dynamic) |
如果启用,则在 schema 推断期间,ClickHouse 会对包含不同数据类型值的 JSON 数组使用 Array(Dynamic) 类型。
示例:
SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=1;
DESC format(JSONEachRow, '{"a" : [42, "hello", [1, 2, 3]]}');┌─name─┬─type───────────┐
│ a │ Array(Dynamic) │
└──────┴────────────────┘SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=0;
DESC format(JSONEachRow, '{"a" : [42, "hello", [1, 2, 3]]}');┌─name─┬─type─────────────────────────────────────────────────────────────┐
│ a │ Tuple(Nullable(Int64), Nullable(String), Array(Nullable(Int64))) │
└──────┴──────────────────────────────────────────────────────────────────┘默认启用。
input_format_json_infer_incomplete_types_as_strings
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.9 | 1 | 默认允许在 JSON 格式的 schema 推断 期间将不完整类型推断为 String |
在 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 的错误。
示例:
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
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.7 | 0 | 新增设置 |
将 Map 列反序列化为元组的 JSON 数组。
默认禁用。
input_format_json_max_depth
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.8 | 1000 | 在之前的版本中,该值不受限制,但这并不安全。 |
JSON 中字段的最大深度。这不是严格限制,无需精确执行。
input_format_json_max_object_size
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.8 | 536870912 | 新增设置,用于限制单个 JSON 对象的最大字节大小 |
单个 JSON 对象允许的最大字节大小。超过此限制的对象将被拒绝,因为它们很可能格式不正确。这可防止格式不正确的 JSON 文档被作为单个对象解析时导致内存耗尽。并行和非并行解析路径均采用相同的限制。设为 0 可禁用此检查。
input_format_json_max_string_column_growth_step
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.8 | 0 | 新增设置,用于在物化 JSON 时限制 JSON 列内部 String 缓冲区按 2 的幂扩容,从而控制过度分配。 |
从字符串解析 JSON 并构建 JSON 列的内部 String 缓冲区时,将按 2 的幂扩容的上限设为此字节数:保留容量达到该值后,缓冲区将以此大小为增量扩容,而非翻倍。这样可控制大型 JSON 列的过度分配。0 表示不设上限 (始终翻倍) 。
input_format_json_named_tuples_as_objects
将命名元组列解析为 JSON 对象。
默认启用。
input_format_json_read_arrays_as_strings
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.9 | 1 | 默认允许在 JSON 输入格式中将数组读取为字符串 |
允许在 JSON 输入格式中将 JSON 数组解析为字符串。
示例:
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
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.1 | 1 | 默认允许在 JSON 格式中将布尔值作为字符串读取 |
允许在 JSON 输入格式中将布尔值作为字符串解析。
默认启用。
input_format_json_read_numbers_as_strings
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.9 | 1 | 默认允许在 JSON 格式中将数字按字符串读取 |
允许在 JSON 输入格式中将数字按字符串解析。
默认启用。
input_format_json_read_objects_as_strings
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.1 | 1 | 在 object 类型仍处于 Experimental 阶段时,启用将嵌套 JSON 对象作为 String 读取 |
允许在 JSON 输入格式中将 JSON 对象按 String 解析。
示例:
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
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.4 | 1 | 允许保存包含错误转义序列的 JSON 字符串 |
如果 JSON 输入格式中的 JSON 字符串包含错误的转义序列,则抛出异常。如果禁用,错误的转义序列将按原样保留在数据中。
默认启用。
input_format_json_try_infer_named_tuples_from_objects
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.9 | 1 | 默认尝试从 JSON 对象推断命名元组 |
如果启用,在进行 schema 推断时,ClickHouse 将尝试从 JSON 对象中推断命名元组。 生成的命名元组将包含样本数据中所有对应 JSON 对象里的全部元素。
示例:
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
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.9 | 0 | 默认情况下,不会在 JSON 格式中从字符串推断数值,以避免可能出现的解析错误 |
如果启用,在进行 schema 推断时,ClickHouse 将尝试从字符串字段中推断数值。 如果 JSON 数据中包含带引号的 UInt64 数值,此设置会很有用。
默认禁用。
input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.3 | 0 | 在从 JSON 对象推断命名元组时,允许对有歧义的路径使用 String 类型 |
在从 JSON 对象推断命名元组时,如果路径存在歧义,则使用 String 类型而不是抛出异常
input_format_json_validate_types_from_metadata
对于 JSON/JSONCompact/JSONColumnsWithMetadata 输入格式,如果此设置为 1, 则会将输入数据元数据中的类型与表中对应列的类型进行比较。
默认启用。
input_format_max_block_size_bytes
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.5 | 0 | 新增设置:限制输入格式创建的块大小(按字节计) |
限制输入格式在数据解析期间形成的块大小 (按字节计) 。用于基于行的输入格式,且块在 ClickHouse 侧生成时生效。 0 表示不限制字节大小。
input_format_max_block_wait_ms
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.2 | 0 | 新增设置:限制输入格式在发出块前的最长等待时间(毫秒) |
限制基于行的输入格式在解析期间发出块之前的最长等待时间 (以毫秒为单位) 。0 表示不限制。
示例:将 Wikipedia 的最近更改流式写入 ClickHouse
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 0input_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 dump 中读取数据的表名
input_format_native_allow_types_conversion
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.3 | 1 | 允许在 Native 输入格式中进行类型转换 |
允许在 Native 输入格式中进行类型转换
input_format_native_decode_types_in_binary_format
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.7 | 0 | 新增设置,允许在 Native 输出格式中以二进制格式读取类型名称 |
在 Native 输入格式中,以二进制格式读取数据类型,而不是类型名称
input_format_null_as_default
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 21.1 | 1 | 默认允许在输入格式中将 NULL 作为默认值插入 |
启用或禁用使用默认值初始化 NULL 字段;前提是这些字段的 Data type 不是 Nullable。
如果列类型不是 Nullable 且此设置已禁用,那么插入 NULL 会引发异常。如果列类型是 Nullable,则无论此设置如何,NULL 值都会按原样插入。
此设置适用于大多数输入格式。
对于复杂的默认表达式,还必须启用 input_format_defaults_for_omitted_fields。
可能的值:
- 0 — 向非 Nullable 列中插入
NULL会引发异常。 - 1 —
NULL字段会使用列的默认值进行初始化。
input_format_orc_allow_missing_columns
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.12 | 1 | 默认允许 ORC 文件缺失列 |
读取 ORC 输入格式时允许缺失列
input_format_orc_case_insensitive_column_matching
匹配 ORC 列与 CH columns 时忽略大小写。
input_format_orc_dictionary_as_low_cardinality
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.10 | 1 | 读取 ORC 文件时,将 ORC 字典编码的列按 LowCardinality 列处理 |
读取 ORC 文件时,将 ORC 字典编码的列按 LowCardinality 列处理。
input_format_orc_filter_push_down
读取 ORC 文件时,可根据 ORC 元数据中的 WHERE/PREWHERE 表达式、最小/最大统计信息或布隆过滤器,跳过整个 stripe 或行组。
input_format_orc_reader_time_zone_name
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.7 | GMT | ORC 行读取器使用的时区名称,默认时区为 GMT。 |
ORC 行读取器使用的时区名称,默认时区为 GMT。
input_format_orc_row_batch_size
读取 ORC 条带时的批次大小。
input_format_orc_skip_columns_with_unsupported_types_in_schema_inference
在对 ORC 格式进行 schema 推断时,跳过类型不受支持的列
input_format_parallel_parsing
启用或禁用在保持顺序不变的情况下对数据格式进行并行解析。仅支持 TabSeparated (TSV)、TSKV、CSV 和 JSONEachRow 格式。
可能的值:
- 1 — 启用。
- 0 — 禁用。
input_format_parquet_allow_geoparquet_parser
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.5 | 1 | 用于在 Parquet 文件中启用 geo 列的新设置 |
使用 geo 列解析器将 Array(UInt8) 转换为 Point/MultiPoint/Linestring/Polygon/MultiLineString/MultiPolygon 类型
input_format_parquet_allow_missing_columns
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.12 | 1 | 默认允许 Parquet 文件中缺失的列 |
读取 Parquet 输入格式时允许缺失的列
input_format_parquet_bloom_filter_push_down
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.5 | 1 | 读取 Parquet 文件时,可根据 Parquet 元数据中的 WHERE/PREWHERE 表达式和布隆过滤器跳过整个行组。 |
| 24.10 | 0 | 读取 Parquet 文件时,可根据 Parquet 元数据中的 WHERE/PREWHERE 表达式和布隆过滤器跳过整个行组。 |
读取 Parquet 文件时,可根据 Parquet 元数据中的 WHERE 表达式和布隆过滤器跳过整个行组。
input_format_parquet_case_insensitive_column_matching
匹配 Parquet 列和 CH columns 时忽略大小写。
input_format_parquet_dictionary_filter_push_down
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.8 | 1048576 | 新增设置:根据字典页内容启用 Parquet 行组裁剪(reader v3)。该值指定应用此优化时字典页允许的最大大小(字节);设为 0(此前行为)则禁用此优化。 |
读取 Parquet 文件 (使用 reader v3) 时,如果某个列块的所有数据页均采用字典编码,则会根据 WHERE/PREWHERE 表达式和字典页内容跳过整个行组。该值指定应用此优化时字典页允许的最大大小 (字节) ;设为 0 可禁用此优化。两者均可用时,此设置的优先级高于 布隆过滤器。
input_format_parquet_enable_json_parsing
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.6 | 1 | 读取 Parquet 文件时,将 JSON 列解析为 ClickHouse JSON 列。 |
读取 Parquet 文件时,将 JSON 列解析为 ClickHouse JSON 列。
input_format_parquet_enable_row_group_prefetch
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.10 | 1 | 在解析 Parquet 时启用行组预取。当前仅单线程解析支持预取。 |
在解析 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
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.11 | 1 | 对 parquet 的“无时区本地时间”类型使用更合适的 DateTime64(..., 'UTC') 类型。 |
确定当 isAdjustedToUTC=false 时,schema inference 为 Parquet 时间戳推断使用的数据类型。若为 true:DateTime64(…, 'UTC');若为 false:DateTime64(…)。这两种行为都不完全正确,因为 ClickHouse 没有表示本地挂钟时间的数据类型。虽然有些反直觉,但 true 可能反而是相对没那么错误的选项,因为将 UTC 时间戳格式化为 String 时,会得到正确的本地时间表示。
input_format_parquet_max_block_size
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.6 | 65409 | 增大 Parquet 读取器的块大小。 |
Parquet 读取器的最大块大小。
input_format_parquet_memory_high_watermark
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.8 | 4294967296 | 新设置 |
Parquet 读取器 v3 的近似内存上限。用于限制可并行读取的行组或列数。在一次查询中读取多个文件时,该限制针对这些文件的总内存使用量。
input_format_parquet_memory_low_watermark
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.8 | 2097152 | 新设置 |
如果内存使用低于该阈值,则会更积极地调度预取操作。例如,当需要通过网络读取大量小型布隆过滤器时,这一设置可能会很有用。
input_format_parquet_page_filter_push_down
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.8 | 1 | 新增设置(当 input_format_parquet_use_native_reader_v3 被禁用时不生效) |
使用列索引中的最小值/最大值跳过数据页。
input_format_parquet_prefer_block_bytes
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.6 | 16744704 | Parquet 读取器 输出的平均块字节数。 |
Parquet 读取器 输出的平均块字节数
input_format_parquet_preserve_order
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.5 | 0 | 允许 Parquet 读取器 为获得更好的并行度而重排行。 |
从 Parquet 文件 读取时避免重排行。不建议这样做,因为通常无法保证行顺序,而且查询管道的其他部分也可能打乱该顺序。请改用 ORDER BY _row_number。
input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference
在对 Parquet 进行 schema 推断 时,跳过具有 unsupported types 的列
input_format_parquet_spatial_filter_push_down
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.8 | 1 | 新增设置:基于空间谓词和边界框统计信息跳过 GeoParquet 行组和页面 |
读取 GeoParquet 文件时,基于 WHERE 子句中的空间谓词和 Parquet 元数据中的几何边界框统计信息 (geospatial_statistics.bbox 或 covering.bbox 列) 跳过整个行组;结合 input_format_parquet_page_filter_push_down,还可跳过单个页面。
input_format_parquet_use_offset_index
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.8 | 1 | 新增设置(当 input_format_parquet_use_native_reader_v3 被禁用时无效) |
在未使用页面过滤时,微调了从 Parquet 文件读取页面的方式。
input_format_parquet_verify_checksums
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.11 | 1 | 新增设置。 |
读取 Parquet 文件时验证页校验和。
input_format_protobuf_flatten_google_wrappers
为常规的非 Nested 列启用 Google wrapper,例如,String 列 str 可使用 google.protobuf.StringValue 'str'。对于 Nullable 列,空 wrapper 会被识别为默认值,缺失的则会被识别为 null 值
input_format_protobuf_oneof_presence
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 25.9 | 0 | 新设置 |
通过在特殊列中设置枚举值,指示找到的是 protobuf oneof 中的哪个字段
input_format_protobuf_skip_fields_with_unsupported_types_in_schema_inference
在对 Protobuf 格式进行 schema 推断 时,跳过类型不受支持的字段
input_format_read_datetime_number_as_raw_value
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 26.8 | 0 | 从 26.8 起,`JSON` 和 `Values`/`Quoted` 路径中 `DateTime`/`DateTime64` 列的未加引号数字(以及 `JSONExtract` 和类型化 `JSON` 中的数字)均表示以秒为单位的 Unix 时间戳,与 `Values` 格式、`CAST` 和 `toDateTime64` 的行为一致。将此设置为 `true`(或使用 `SET compatibility = '26.7'`)可恢复 26.8 之前的行为:传入 `DateTime64` 列的未加引号整数会被读取为原始标度值(ticks)。制表符分隔、CSV 及其他转义/完整文本格式不受此设置控制。 |
将 DateTime/DateTime64 列中未加引号的整数读取为底层原始值——对于
DateTime 是秒,对于 DateTime64 是按列精度计算的 ticks——而不是以秒为单位的 Unix 时间戳。
默认禁用:未加引号的数字表示以秒为单位的 Unix 时间戳 (可带子秒级精度) ,
与 Values 格式、CAST 和 toDateTime64 的行为一致。启用此设置 (或使用 SET compatibility = '26.7') 可
恢复至 26.7 (含) 版本的行为:传入 DateTime64
列的未加引号整数会被解释为原始标度值 (ticks) 。旧版路径仅接受此类未加引号整数:
启用该设置后,带有小数部分或指数部分的数字会被行输入路径拒绝
(与 26.8 之前相同) ;而在 JSONExtract 和类型化 JSON 类型中,小数数字仍会被作为
DateTime64 的秒读取,但会被 DateTime 拒绝 (同样与 26.8 之前相同) 。在 Values 格式本身中,
被流式解析器拒绝的数字会回退到 SQL 表达式求值,并被读取为秒,
无论是在 26.8 之前还是启用此设置后都是如此——因此,Values 对小数数字的行为在所有
配置中均相同。
此设置仅控制 JSON、Values/Quoted 以及 JSONExtract/类型化 JSON 路径 (Quoted 路径
涵盖所有使用 Quoted 转义规则解析字段的格式:Values、MySQLDump,以及
配置了 Quoted 字段转义的 Template/CustomSeparated/Regexp) 。制表符分隔、CSV 及其他
转义/完整文本格式不受影响:在这些格式中,较大的未加引号 DateTime64 数字仍会被读取为 ticks。
input_format_record_errors_file_path
读取文本格式 (CSV、TSV) 时,用于记录错误的文件路径。
input_format_skip_unknown_fields
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 22.6 | 1 | 优化某些输入格式对列子集的读取 |
启用或禁用跳过插入额外数据。
写入数据时,如果输入数据包含目标表中不存在的列,ClickHouse 会抛出异常。如果启用了跳过,ClickHouse 不会插入这些额外数据,也不会抛出异常。
支持的格式:
- JSONEachRow (以及其他 JSON 格式)
- BSONEachRow (以及其他 JSON 格式)
- TSKV
- 所有带有 WithNames/WithNamesAndTypes 后缀的格式
- MySQLDump
- Native
可能的值:
- 0 — 已禁用。
- 1 — 已启用。
input_format_try_infer_dates
如果启用,ClickHouse 会在文本格式的 schema inference 过程中尝试从字符串字段中推断 Date 类型。如果输入数据中某一列的所有字段都成功解析为日期,则结果类型为 Date;如果至少有一个字段未能解析为日期,则结果类型为 String。
默认已启用。
input_format_try_infer_datetimes
如果启用,ClickHouse 会在文本格式的 schema inference 中尝试从字符串字段推断 DateTime64 类型。如果输入数据中某一列的所有字段都成功解析为日期时间,结果类型将为 DateTime64;如果其中至少有一个字段未能解析为日期时间,结果类型则为 String。
默认已启用。
input_format_try_infer_datetimes_only_datetime64
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.8 | 0 | 允许在数据格式中推断为 DateTime 而非 DateTime64 |
启用 input_format_try_infer_datetimes 时,只推断 DateTime64,不推断 DateTime 类型
input_format_try_infer_exponent_floats
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.2 | 0 | 默认不推断采用指数表示法的浮点数 |
在文本格式中进行 schema 推断时,尝试推断采用指数表示法的浮点数 (JSON 除外,其中采用指数表示法的数值始终会被推断)
input_format_try_infer_integers
如果启用,ClickHouse 会在文本格式的 schema 推断中尝试将整数而非浮点数推断为结果类型。如果输入数据中某一列的所有数字都是整数,则结果类型为 Int64;如果至少有一个数字是浮点数,则结果类型为 Float64。
默认启用。
input_format_try_infer_variants
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.9 | 0 | 当列/数组元素存在多种可能类型时,在文本格式的 schema 推断中尝试推断 Variant 类型 |
如果启用,ClickHouse 会在文本格式的 schema 推断中,当列/数组元素存在多种可能类型时,尝试推断 Variant 类型。
可选值:
- 0 — 已禁用。
- 1 — 已启用。
input_format_tsv_allow_variable_number_of_columns
忽略 TSV 输入中的多余列 (如果文件中的列数超出预期) ,并将 TSV 输入中缺失的字段视为默认值
input_format_tsv_crlf_end_of_line
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 24.5 | 0 | 启用读取采用 CRLF 行尾的 TSV 格式 |
如果将其设置为 true,file 函数将读取使用 \r\n 而非 \n 的 TSV 格式。
input_format_tsv_detect_header
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 23.1 | 1 | 默认检测 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 format:在使用 template 解析和解释表达式时,会检查字面量的实际类型,以避免可能出现的溢出和精度问题。
input_format_values_deduce_templates_of_expressions
对于 Values format:如果字段无法通过流式解析器解析,则会运行 SQL 解析器,推导出 SQL 表达式的模板,尝试使用该模板解析所有行,然后对所有行中的该表达式求值。
input_format_values_interpret_expressions
对于 Values format,如果字段无法通过流式解析器解析,则运行 SQL 解析器,并尝试将其作为 SQL 表达式进行解释。
input_format_with_names_use_header
版本历史
| 版本 | 默认值 | 注释 |
|---|---|---|
| 20.5 | 1 | 对带有 WithNames/WithNamesAndTypes 后缀的格式启用名称请求头 |
启用或禁用在插入数据时检查列顺序。
为提高插入性能,如果你可以确定输入数据的列顺序与目标表一致,建议禁用此检查。
支持的格式:
- CSVWithNames
- CSVWithNamesAndTypes
- TabSeparatedWithNames
- TabSeparatedWithNamesAndTypes
- JSONCompactEachRowWithNames
- JSONCompactEachRowWithNamesAndTypes
- JSONCompactStringsEachRowWithNames
- JSONCompactStringsEachRowWithNamesAndTypes
- RowBinaryWithNames
- RowBinaryWithNamesAndTypes
- CustomSeparatedWithNames
- CustomSeparatedWithNamesAndTypes
可能的值:
- 0 — 禁用。
- 1 — 启用。
input_format_with_types_use_header
控制格式解析器是否应检查输入数据中的数据类型是否与目标表中的数据类型匹配。
支持的格式:
- CSVWithNamesAndTypes
- TabSeparatedWithNamesAndTypes
- JSONCompactEachRowWithNamesAndTypes
- JSONCompactStringsEachRowWithNamesAndTypes
- RowBinaryWithNamesAndTypes
- CustomSeparatedWithNamesAndTypes
可能的值:
- 0 — 已禁用。
- 1 — 已启用。