Skip to main content
这些设置是根据源文件自动生成的。

input_format_allow_errors_num

设置从文本格式 (CSV、TSV 等) 读取数据时可接受的最大错误数。 默认值为 0。 请始终与 input_format_allow_errors_ratio 配合使用。 如果在读取行时发生错误,但错误计数器仍小于 input_format_allow_errors_num,ClickHouse 会忽略该行并继续读取下一行。 如果 input_format_allow_errors_numinput_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_numinput_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 推断 时,跳过类型不受支持的列

input_format_arrow_use_native_reader

在 Arrow 和 ArrowStream 格式中使用 ClickHouse 原生读取器,而不是基于 Apache Arrow 库的读取器。

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

在 RowBinaryWithNamesAndTypes 输入格式中,以二进制格式读取数据类型,而不是类型名称

input_format_binary_max_type_complexity

解码二进制类型时允许的最大类型节点数 (不是深度,而是节点总数) 。Map(String, UInt32) = 3 个节点。可防止恶意输入。0 = 不限制。

input_format_binary_read_json_as_string

在 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

定义通过各种格式 (包括但不限于 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 列。

input_format_csv_detect_header

自动检测 CSV 格式中的名称和类型请求头

input_format_csv_empty_as_default

将 CSV 输入中的空字段按默认值处理。

input_format_csv_enum_as_number

将 CSV 格式中插入的枚举值视为枚举索引

input_format_csv_missing_nullable_as_empty_string

控制如何将 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

将输入数据中带引号的 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

自动检测 CustomSeparated format 中包含名称和类型的请求头

input_format_custom_skip_trailing_empty_lines

跳过 CustomSeparated format 末尾的空行

input_format_defaults_for_omitted_fields

执行 INSERT 查询时,将省略的输入列值替换为对应列的默认值。此选项适用于 JSONEachRow (以及其他 JSON 格式) 、CSVTabSeparatedTSKVParquetArrowAvroORCNative 格式,以及带有 WithNames/WithNamesAndTypes 后缀的格式。
启用此选项后,服务器会将扩展的表元数据发送给客户端。这会额外占用服务器的计算资源,并可能降低性能。
可能的值:
  • 0 — 禁用。
  • 1 — 启用。

input_format_force_null_for_omitted_fields

强制将被省略的字段初始化为 NULL 值

input_format_geojson_unsupported_geometry_handling

控制在读取 GeoJSON 输入时,如果需要将一种无法在 ClickHouse 的 Geometry 类型中表示的有效 GeoJSON 几何类型 (如 GeometryCollectionMultiPoint) 存储到 geometry 列中时,系统的处理方式。 可能的值:
  • 'throw' (默认) — 抛出异常。
  • 'null' — 为 geometry 列插入 NULL 值并继续解析。
这仅在 geometry 列被 materialized 时适用。当它不是请求的输出列时,此类几何对象只会验证其格式是否正确,但不会触发该处理。

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 数据。 支持的格式: 可能的值:
  • 0 — 禁用。
  • 1 — 启用。
另请参阅:

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) 类型。 示例:
默认启用。

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 的错误。 示例:
结果:
默认启用。

input_format_json_map_as_array_of_tuples

将 Map 列反序列化为元组的 JSON 数组。 默认禁用。

input_format_json_max_depth

JSON 中字段的最大深度。这不是严格限制,无需精确执行。

input_format_json_named_tuples_as_objects

将命名元组列解析为 JSON 对象。 默认启用。

input_format_json_read_arrays_as_strings

允许在 JSON 输入格式中将 JSON 数组解析为字符串。 示例:
结果:
默认启用。

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 对象按 String 解析。 示例:
结果:
默认启用。

input_format_json_throw_on_bad_escape_sequence

如果 JSON 输入格式中的 JSON 字符串包含错误的转义序列,则抛出异常。如果禁用,错误的转义序列将按原样保留在数据中。 默认启用。

input_format_json_try_infer_named_tuples_from_objects

如果启用,在进行 schema 推断时,ClickHouse 将尝试从 JSON 对象中推断命名元组。 生成的命名元组将包含样本数据中所有对应 JSON 对象里的全部元素。 示例:
结果:
默认启用。

input_format_json_try_infer_numbers_from_strings

如果启用,在进行 schema 推断时,ClickHouse 将尝试从字符串字段中推断数值。 如果 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

限制基于行的输入格式在解析期间发出块之前的最长等待时间 (以毫秒为单位) 。0 表示不限制。
此选项仅在启用 input_format_connection_handling 时生效。设置该值还会禁用并行解析,并使去重无法实现。
对于流式插入,你还必须设置 min_insert_block_size_rows=0min_insert_block_size_bytes=0。否则,已解析的块仍可能在块合并阶段持续累积在内存中,直到达到这些阈值,从而无法及时插入。
示例:将 Wikipedia 的最近更改流式写入 ClickHouse

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 dump 中读取数据的表名

input_format_native_allow_types_conversion

允许在 Native 输入格式中进行类型转换

input_format_native_decode_types_in_binary_format

在 Native 输入格式中,以二进制格式读取数据类型,而不是类型名称

input_format_null_as_default

启用或禁用使用默认值初始化 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

读取 ORC 输入格式时允许缺失列

input_format_orc_case_insensitive_column_matching

匹配 ORC 列与 CH columns 时忽略大小写。

input_format_orc_dictionary_as_low_cardinality

读取 ORC 文件时,将 ORC 字典编码的列按 LowCardinality 列处理。

input_format_orc_filter_push_down

读取 ORC 文件时,可根据 ORC 元数据中的 WHERE/PREWHERE 表达式、最小/最大统计信息或布隆过滤器,跳过整个 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)TSKVCSVJSONEachRow 格式。 可能的值:
  • 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 文件时,可根据 Parquet 元数据中的 WHERE 表达式和布隆过滤器跳过整个行组。

input_format_parquet_case_insensitive_column_matching

匹配 Parquet 列和 CH columns 时忽略大小写。

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 时,schema inference 为 Parquet 时间戳推断使用的数据类型。若为 true:DateTime64(…, ‘UTC’);若为 false:DateTime64(…)。这两种行为都不完全正确,因为 ClickHouse 没有表示本地挂钟时间的数据类型。虽然有些反直觉,但 true 可能反而是相对没那么错误的选项,因为将 UTC 时间戳格式化为 String 时,会得到正确的本地时间表示。

input_format_parquet_max_block_size

Parquet 读取器的最大块大小。

input_format_parquet_memory_high_watermark

Parquet 读取器 v3 的近似内存上限。用于限制可并行读取的行组或列数。在一次查询中读取多个文件时,该限制针对这些文件的总内存使用量。

input_format_parquet_memory_low_watermark

如果内存使用低于该阈值,则会更积极地调度预取操作。例如,当需要通过网络读取大量小型布隆过滤器时,这一设置可能会很有用。

input_format_parquet_page_filter_push_down

使用列索引中的最小值/最大值跳过数据页。

input_format_parquet_prefer_block_bytes

Parquet 读取器 输出的平均块字节数

input_format_parquet_preserve_order

从 Parquet 文件 读取时避免重排行。不建议这样做,因为通常无法保证行顺序,而且查询管道的其他部分也可能打乱该顺序。请改用 ORDER BY _row_number

input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference

在对 Parquet 进行 schema 推断 时,跳过具有 unsupported types 的列

input_format_parquet_use_offset_index

在未使用页面过滤时,微调了从 Parquet 文件读取页面的方式。

input_format_parquet_verify_checksums

读取 Parquet 文件时验证页校验和。

input_format_protobuf_flatten_google_wrappers

为常规的非 Nested 列启用 Google wrapper,例如,String 列 str 可使用 google.protobuf.StringValue 'str'。对于 Nullable 列,空 wrapper 会被识别为默认值,缺失的则会被识别为 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 不会插入这些额外数据,也不会抛出异常。 支持的格式: 可能的值:
  • 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

启用 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 推断中,当列/数组元素存在多种可能类型时,尝试推断 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 格式。

input_format_tsv_detect_header

自动检测 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

启用或禁用在插入数据时检查列顺序。 为提高插入性能,如果你可以确定输入数据的列顺序与目标表一致,建议禁用此检查。 支持的格式: 可能的值:
  • 0 — 禁用。
  • 1 — 启用。

input_format_with_types_use_header

控制格式解析器是否应检查输入数据中的数据类型是否与目标表中的数据类型匹配。 支持的格式: 可能的值:
  • 0 — 已禁用。
  • 1 — 已启用。
最后修改于 2026年7月23日