跳转到主要内容
ClickHouse 几乎可以自动确定所有受支持的输入格式的输入数据结构。 本文将介绍何时会使用 schema 推断、它在不同输入格式下如何工作，以及可用于控制它的设置。

​
用法

当 ClickHouse 需要以特定数据格式读取数据，而其结构未知时，就会使用 schema 推断。 这些表函数都支持可选参数 structure，用于指定输入数据的结构。如果未指定该参数，或将其设置为 auto，则会根据数据自动推断结构。 示例： 假设 user_files 目录中有一个采用 JSONEachRow 格式的文件 hobbies.jsonl，内容如下：
ClickHouse 无需指定其结构，即可读取这些数据：
注意：格式 JSONEachRow 是根据文件扩展名 .jsonl 自动识别的。 你可以使用 DESCRIBE 查询来查看自动识别的结构：
如果在 CREATE TABLE 查询中未指定列列表，系统会自动根据数据推断表结构。 示例： 我们使用文件 hobbies.jsonl。可以创建一个使用 File 引擎的表，并读取该文件中的数据：

​
clickhouse-local

clickhouse-local 提供可选参数 -S/--structure，用于指定输入数据的结构。如果未指定该参数，或将其设为 auto，则会根据数据自动推断其结构。 示例： 以文件 hobbies.jsonl 为例。我们可以使用 clickhouse-local 查询该文件中的数据：

​
使用插入表的结构

当使用表函数 file/s3/url/hdfs 向表中插入数据时， 可以选择使用插入表的结构，而不是从数据中提取结构。 这样可以提升插入性能，因为 schema 推断 可能会耗费一些时间。此外，当表具有优化后的 schema 时，这种方式也很有帮助，因此 无需执行类型转换。 有一个特殊设置 use_structure_from_insertion_table_in_table_functions 用于控制此行为。它有 3 个可能的值：
  • 0 - 表函数将从数据中提取结构。
  • 1 - 表函数将使用插入表的结构。
  • 2 - ClickHouse 将自动判断是否可以使用插入表的结构，或使用 schema 推断。默认值。
示例 1： 让我们创建一个具有以下结构的表 hobbies1：
并从文件 hobbies.jsonl 中插入数据：
在这种情况下，文件中的所有列都会不作修改地插入表中，因此 ClickHouse 会使用插入表的结构，而不是进行 schema 推断。 示例 2： 创建具有以下结构的表 hobbies2：
并从 hobbies.jsonl 文件中插入数据：
在这种情况下，SELECT 查询中的所有列都存在于该表中，因此 ClickHouse 将使用插入表的结构。 请注意，这仅适用于支持读取部分列的输入格式，例如 JSONEachRow、TSKV、Parquet 等 (因此例如 TSV 格式就不适用) 。 示例 3： 让我们创建表 hobbies3，其结构如下：
并从 hobbies.jsonl 文件中插入数据：
在这种情况下，SELECT 查询中使用了列 id，但该表并没有这一列 (而是有一个名为 identifier 的列) ， 因此 ClickHouse 无法使用插入表的结构，而会使用 schema 推断。 示例 4： 让我们创建表 hobbies4，其结构如下：
然后从文件 hobbies.jsonl 插入数据：
在这种情况下，SELECT 查询中对列 hobbies 做了一些处理后再将其插入表中，因此 ClickHouse 无法使用插入目标表的结构，而会使用 schema 推断。

​
schema 推断缓存

对于大多数输入格式，schema 推断会读取部分数据来确定其结构，这个过程可能需要一些时间。 为了避免 ClickHouse 每次从同一文件读取数据时都重复推断相同的 schema，已推断出的 schema 会被缓存；当再次访问同一文件时，ClickHouse 会使用缓存中的 schema。 有一些专门用于控制此缓存的设置：
  • schema_inference_cache_max_elements_for_{file/s3/hdfs/url/azure} - 对应表函数可缓存的 schema 最大数量。默认值为 4096。这些设置应在 server 配置中设置。
  • schema_inference_use_cache_for_{file,s3,hdfs,url,azure} - 用于开启/关闭 schema 推断缓存。这些设置可以在查询中使用。
文件的 schema 可能会因数据被修改或 format 设置发生变化而改变。 因此，schema 推断缓存会根据文件来源、format 名称、所使用的 format 设置以及文件的最后修改时间来识别 schema。 注意：在 url 表函数中通过 url 访问的某些文件可能不包含最后修改时间信息；针对这种情况，有一个专门的设置 schema_inference_cache_require_modification_time_for_url。禁用此设置后，对于这类文件，即使没有最后修改时间，也允许使用缓存中的 schema。 此外，还有一个系统表 schema_inference_cache，其中包含当前缓存中的所有 schema，以及系统查询 SYSTEM CLEAR SCHEMA CACHE [FOR File/S3/URL/HDFS] 它可用于清理所有来源的 schema 缓存，或某个特定来源的 schema 缓存。 示例： 让我们尝试从 s3 中的样本数据集 github-2022.ndjson.gz 推断其结构，并看看 schema 推断缓存是如何工作的：
如你所见，第二个查询几乎瞬间就成功了。 下面我们尝试更改一些可能影响推断 schema 的设置：
如你所见，对于同一个文件，并未使用缓存中的 schema，因为会影响 schema 推断的设置已发生更改。 让我们查看 system.schema_inference_cache 表中的内容：
如你所见，同一个文件对应两种不同的 schema。 我们可以使用系统查询清除 schema 缓存：

​
文本格式

对于文本格式，ClickHouse 会按行读取数据，根据格式提取列值， 然后使用一些递归解析器和启发式规则来确定每个值的类型。在 schema 推断中，从数据中读取的最大行数和字节数 由设置 input_format_max_rows_to_read_for_schema_inference (默认值为 25000) 和 input_format_max_bytes_to_read_for_schema_inference (默认值为 32Mb) 控制。 默认情况下，所有推断出的类型均为 Nullable，但你可以通过设置 schema_inference_make_columns_nullable 更改这一行为 (请参见设置部分中的示例) 。

​
JSON 格式

在 JSON 格式中，ClickHouse 会按照 JSON 规范解析值，并尝试为其推断最合适的数据类型。 下面介绍其工作原理、可推断的类型，以及在 JSON formats 中可使用的特定设置。 示例 在本节及后续内容中，示例将使用 format 表函数。 整数、浮点数、Bool、String：
日期、日期时间：
Arrays：
如果数组包含 null，ClickHouse 将根据其他数组元素来推断类型：
如果数组包含不同类型的值，且设置 input_format_json_infer_array_of_dynamic_from_array_of_different_types 已启用 (默认启用) ，则该数组的类型将为 Array(Dynamic)：
命名元组： 当启用设置 input_format_json_try_infer_named_tuples_from_objects 时，ClickHouse 会在进行 schema 推断 期间尝试从 JSON 对象中推断命名元组。 生成的命名元组将包含样本数据中所有对应 JSON 对象里的全部元素。
未命名元组： 如果禁用设置 input_format_json_infer_array_of_dynamic_from_array_of_different_types，我们会在 JSON 格式中将元素类型不同的 Array 视为未命名元组。
如果某些值为 null 或为空，则使用其他行中对应值的类型：
Map： 在 JSON 中，可以将值类型相同的对象读取为 Map 类型。 注意：只有在禁用设置 input_format_json_read_objects_as_strings 和 input_format_json_try_infer_named_tuples_from_objects 时，此功能才会生效。
嵌套复杂数据类型：
如果 ClickHouse 无法确定某个键的类型，例如数据中只包含 null/空对象/空数组，那么在启用设置 input_format_json_infer_incomplete_types_as_strings 时将使用 String 类型；否则会抛出异常：

​
JSON 设置

input_format_json_try_infer_numbers_from_strings
启用此设置后，可以从字符串值中推断出数值。 此设置默认处于禁用状态。 示例：
input_format_json_try_infer_named_tuples_from_objects
启用此设置后，可以从 JSON 对象中推断命名元组。生成的命名元组将包含样本数据中所有对应 JSON 对象里的全部元素。 当 JSON 数据不是稀疏数据时，此设置会很有用，因为数据样本将包含所有可能的对象键。 此设置默认启用。 示例
Query
Response
Query
Response
input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects
启用此设置后，在从 JSON 对象推断命名元组时 (启用 input_format_json_try_infer_named_tuples_from_objects 的情况下) ，对于存在歧义的路径将使用 String 类型，而不是抛出异常。 即使存在歧义路径，也可以将 JSON 对象读取为命名元组。 默认禁用。 示例 在该设置禁用时：
Query
Response
启用此设置后：
Query
Response
input_format_json_read_objects_as_strings
启用此设置后，可以将嵌套 JSON 对象读取为字符串。 此设置可用于在不使用 JSON object 类型的情况下读取嵌套 JSON 对象。 此设置默认已启用。 注意：只有在禁用 input_format_json_try_infer_named_tuples_from_objects 设置时，启用此设置才会生效。
input_format_json_read_numbers_as_strings
启用此设置后，可将数值读取为字符串。 此设置默认启用。 示例
input_format_json_read_bools_as_numbers
启用此设置后，可以将 Bool 值按数值读取。 此设置默认启用。 示例：
input_format_json_read_bools_as_strings
启用此设置后，可将 Bool 值按字符串读取。 此设置默认启用。 示例：
input_format_json_read_arrays_as_strings
启用此设置后，可以将 JSON 数组值读取为字符串。 此设置默认启用。 示例
input_format_json_infer_incomplete_types_as_strings
启用此设置后，在进行 schema 推断时，对于数据样本中仅包含 Null/{}/[] 的 JSON 键，可使用 String 类型。 在 JSON formats 中，如果启用了所有相应设置 (这些设置默认均为启用) ，则任何值都可以读取为 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 的错误。 Example：
Query
Response

​
CSV

在 CSV 格式中，ClickHouse 会根据分隔符从行中提取列值。ClickHouse 要求除数字和字符串之外的所有类型都用双引号括起来。如果值位于双引号内，ClickHouse 会尝试使用递归解析器解析 引号内的数据，然后尽量为其找到最合适的数据类型。如果值不在双引号内，ClickHouse 会尝试将其解析为数字； 如果该值不是数字，ClickHouse 会将其视为字符串。 如果你不希望 ClickHouse 通过某些解析器和启发式方法来确定复杂类型，可以禁用设置 input_format_csv_use_best_effort_in_schema_inference， 这样 ClickHouse 会将所有列都视为 String。 如果启用了设置 input_format_csv_detect_header，ClickHouse 会在推断 schema 时尝试检测包含列名 (以及可能包含类型) 的表头。该设置默认启用。 示例： 整数、浮点数、布尔值、字符串：
未加引号的字符串：
日期、日期时间：
数组：
如果数组中包含 NULL，ClickHouse 将使用该数组中其他元素的类型：
Map：
嵌套 数组 和 Map：
如果 ClickHouse 因数据仅包含 null 值而无法确定引号内的类型，就会将其视为 String：
禁用 input_format_csv_use_best_effort_in_schema_inference 设置的示例：
表头自动检测示例 (启用 input_format_csv_detect_header 时) ： 仅列名：
名称和类型：
请注意，只有在至少有一列不是 String 类型时，才能检测到表头。如果所有列都是 String 类型，则无法检测到表头：

​
CSV 设置

input_format_csv_try_infer_numbers_from_strings
启用此设置后，可以从字符串值中推断数值。 此设置默认禁用。 示例：

​
TSV/TSKV

在 TSV/TSKV 格式中，ClickHouse 会根据表格分隔符从行中提取列值，然后使用递归解析器对提取出的值进行解析，以确定最合适的类型。如果无法确定类型，ClickHouse 会将该值视为 String。 如果您不希望 ClickHouse 使用某些解析器和启发式方法来尝试确定复杂类型，可以禁用设置 input_format_tsv_use_best_effort_in_schema_inference， 这样 ClickHouse 会将所有列都视为 String。 如果启用了设置 input_format_tsv_detect_header，ClickHouse 会在推断 schema 时尝试检测包含列名 (以及可能还有类型) 的表头。此设置默认启用。 示例： 整数、浮点数、布尔值、字符串：
日期、日期时间：
数组：
如果数组包含 null 值，ClickHouse 将使用数组中其他元素的类型：
Tuples：
Map：
嵌套数组、Tuple 和 Map：
如果 ClickHouse 无法确定类型 (因为数据仅包含 NULL 值) ，ClickHouse 会将其视为 String：
禁用 input_format_tsv_use_best_effort_in_schema_inference 设置的示例：
表头自动检测示例 (启用 input_format_tsv_detect_header 时) ： 仅列名：
名称和类型：
请注意，只有在至少有一列不是 String 类型时，才能识别表头。如果所有列都是 String 类型，则无法识别表头：

​
值

在 Values 格式中，ClickHouse 从行中提取列值，然后使用递归解析器对其进行解析，解析方式与字面量的解析方式类似。 示例： 整数、浮点数、Bool、String：
日期、日期时间：
Arrays (数组) ：
如果数组中包含 null，ClickHouse 将根据其他数组元素来推断类型：
元组：
Map：
嵌套的 Array、Tuple 和 Map：
如果 ClickHouse 无法确定类型 (因为数据仅包含 NULL) ，则会抛出异常：
禁用 input_format_tsv_use_best_effort_in_schema_inference 设置的示例：

​
CustomSeparated

在 CustomSeparated 格式中，ClickHouse 会先根据指定的分隔符从每一行中提取所有列值，然后再根据转义规则尝试推断每个值的数据类型。 如果启用了设置 input_format_custom_detect_header，ClickHouse 会在推断 schema 时尝试检测包含列名 (以及可能还包含类型) 的表头。此设置默认启用。 示例
表头自动检测示例 (启用 input_format_custom_detect_header 时) ：

​
Template

在 Template 格式中，ClickHouse 会先按照指定模板从行中提取所有列值，然后再根据各自的转义规则尝试推断 每个值的数据类型。 示例 假设我们有一个名为 resultset 的文件，内容如下：
以及内容如下的文件 row_format：
接着我们可以执行以下查询：

​
Regexp

与 Template 类似，在 Regexp 格式中，ClickHouse 会先根据指定的正则表达式从每一行中提取所有列值，再按照指定的转义规则尝试推断每个值的数据类型。 示例

​
文本格式设置

​
input_format_max_rows_to_read_for_schema_inference/input_format_max_bytes_to_read_for_schema_inference

这些设置用于控制在进行 schema 推断 时读取的数据量。 读取的行数/字节数越多，schema 推断 所花费的时间就越长，但也越有可能正确推断 types (尤其是在数据包含大量 NULL 值时) 。 默认值：
  • 25000 对应 input_format_max_rows_to_read_for_schema_inference。
  • 33554432 (32 Mb) 对应 input_format_max_bytes_to_read_for_schema_inference。

​
column_names_for_schema_inference

对于没有显式列名的格式，用于 schema 推断 的列名列表。将使用指定的列名，而不是默认的 c1,c2,c3,...。格式：column1,column2,column3,...。 示例

​
schema_inference_hints

在 schema 推断 中使用的列名和类型列表，用于替代自动推断出的类型。格式：‘column_name1 column_type1, column_name2 column_type2, …’。 此设置可用于指定无法自动推断出的列类型，或用于优化 schema。 示例

​
schema_inference_make_columns_nullable $

控制在对不含可空性信息的格式进行 schema inference 时，是否将推断出的类型设为 Nullable。可能的值：
  • 0 - 推断出的类型永远不会是 Nullable，
  • 1 - 所有推断类型都将为 Nullable，
  • 2 或 ‘auto’ - 对于文本格式，仅当列在 schema 推断期间解析的样本中包含 NULL 时，推断出的类型才会是 Nullable；对于强类型格式 (Parquet、ORC、Arrow) ，可空性信息会从文件元数据中获取，
  • 3 - 对于文本格式，使用 Nullable；对于强类型格式，则使用文件元数据。
默认值：3。 示例

​
input_format_try_infer_integers

此设置不适用于 JSON 数据类型。
启用后，ClickHouse 会在文本格式的 schema 推断 中尽量将数值推断为整数而不是浮点数。 如果样本数据中该列的所有数字都是整数，则结果类型为 Int64；如果至少有一个数字是浮点数，则结果类型为 Float64。 如果样本数据只包含整数，且至少有一个正整数超出 Int64 的表示范围，ClickHouse 将推断为 UInt64。 默认启用。 示例

​
input_format_try_infer_datetimes

如果启用，ClickHouse 会在文本格式的 schema 推断中，尝试从字符串字段推断出 DateTime 或 DateTime64 类型。 如果样本数据中某一列的所有字段都成功解析为日期时间，结果类型将为 DateTime 或 DateTime64(9) (如果存在带小数部分的日期时间) ； 如果至少有一个字段未能解析为日期时间，结果类型将为 String。 默认启用。 示例

​
input_format_try_infer_datetimes_only_datetime64

如果启用，即使日期时间值不包含小数部分，只要启用了 input_format_try_infer_datetimes，ClickHouse 也始终会推断为 DateTime64(9)。 默认处于禁用状态。 示例
注意：在 schema 推断期间解析日期时间时，会遵循 date_time_input_format 设置

​
input_format_try_infer_dates

如果启用，ClickHouse 会在文本格式的 schema 推断过程中，尝试从字符串字段中推断出 Date 类型。 如果样本数据中某一列的所有字段都成功解析为日期，则结果类型为 Date； 如果至少有一个字段未解析为日期，则结果类型为 String。 默认启用。 示例

​
input_format_try_infer_exponent_floats

如果启用，ClickHouse 将尝试在文本格式中推断以指数形式表示的浮点数 (JSON 除外，因为 JSON 中以指数形式表示的数值始终会被推断) 。 默认情况下处于禁用状态。 示例

​
自描述格式

自描述格式会在数据本身中包含有关其结构的信息， 例如带有说明的某种头部信息、二进制类型树，或某种表。 为了从这类格式的文件中自动推断 schema，ClickHouse 会读取其中包含 类型信息的部分数据，并将其转换为 ClickHouse 表的 schema。

​
带有 -WithNamesAndTypes 后缀的格式

ClickHouse 支持一些带有 -WithNamesAndTypes 后缀的文本格式。该后缀表示，在实际数据之前，数据中会额外包含两行，分别存放列名和类型。 对此类格式进行 schema 推断时，ClickHouse 会读取前两行并提取列名和类型。 示例

​
带元数据的 JSON 格式

某些 JSON 输入格式 (JSON、JSONCompact、JSONColumnsWithMetadata) 包含带有列名和类型的元数据。 对于这类格式的 schema 推断，ClickHouse 会读取这些元数据。 示例

​
Avro

在 Avro 格式中，ClickHouse 会从数据中读取 schema，并根据以下类型对应关系将其转换为 ClickHouse schema： 不支持其他 Avro 类型。

​
Parquet

在 Parquet 格式中，ClickHouse 会从数据中读取其 schema，并根据以下类型对应关系将其转换为 ClickHouse schema： 不支持其他 Parquet 类型。

​
Arrow

在 Arrow 格式中，ClickHouse 会从数据中读取 schema，并根据以下类型对应关系将其转换为 ClickHouse schema： 不支持其他 Arrow 类型。

​
ORC

在 ORC 格式中，ClickHouse 会从数据中读取 schema，并按照以下类型映射将其转换为 ClickHouse schema： 不支持其他 ORC 类型。

​
Native

Native 格式用于 ClickHouse 内部，并在数据中包含 schema。 在 schema 推断 中，ClickHouse 会直接从数据中读取 schema，无需任何转换。

​
带外部 schema 的格式

这类格式需要在单独的文件中使用特定的 schema 语言来定义数据的 schema。 为了自动从这类格式的文件中推断 schema，ClickHouse 会从单独的文件中读取外部 schema，并将其转换为 ClickHouse 表的 schema。

​
Protobuf

在 Protobuf 格式的 schema 推断中，ClickHouse 使用以下类型映射：

​
CapnProto

在 CapnProto 格式的 schema 推断 中，ClickHouse 使用以下类型映射：

​
强类型二进制格式

在这类格式中，每个序列化值都包含其类型信息 (以及可能包含其名称信息) ，但不包含整个表的信息。 对此类格式进行 schema 推断时，ClickHouse 会逐行读取数据 (最多读取 input_format_max_rows_to_read_for_schema_inference 行或 input_format_max_bytes_to_read_for_schema_inference 字节) ，并从数据中提取 每个值的类型 (以及可能的名称) ，然后将这些类型转换为 ClickHouse 类型。

​
MsgPack

在 MsgPack 格式中，行与行之间没有分隔符，因此如果要对此格式使用 schema 推断，您需要通过设置 input_format_msgpack_number_of_columns 指定表中的列数。ClickHouse 使用以下类型映射： 默认情况下，所有推断出的类型都包含在 Nullable 中，但可以通过设置 schema_inference_make_columns_nullable 进行更改。

​
BSONEachRow

在 BSONEachRow 中，每一行数据都表示为一个 BSON 文档。在进行 schema 推断时，ClickHouse 会逐个读取 BSON 文档，并从数据中提取 值、名称和类型，然后按照以下类型映射将这些类型转换为 ClickHouse 类型： 默认情况下，所有推断出的类型都会包裹在 Nullable 中，但可以通过设置 schema_inference_make_columns_nullable 进行更改。

​
schema 固定的格式

这类格式中的数据始终采用相同的 schema。

​
LineAsString

在这种格式下，ClickHouse 会将数据中的整行读入一个 String 数据类型的单列中。该格式推断出的类型始终为 String，列名为 line。 示例

​
JSONAsString

在这种格式中，ClickHouse 会将数据中的整个 JSON 对象读取到一个 String 数据类型的列中。该格式推断出的类型始终为 String，列名为 json。 示例

​
JSONAsObject

在这种格式中，ClickHouse 会将数据中的整个 JSON 对象读入具有 JSON 数据类型的单个列中。此格式推断出的类型始终为 JSON，列名为 json。 示例

​
schema 推断模式

对一组数据文件进行 schema 推断时，可以使用 2 种不同的模式：default 和 union。 该模式由设置 schema_inference_mode 控制。

​
默认模式

在默认模式下，ClickHouse 假设所有文件都具有相同的 schema，并尝试逐个读取文件来推断 schema，直到成功为止。 示例： 假设我们有 3 个文件 data1.jsonl、data2.jsonl 和 data3.jsonl，内容如下： data1.jsonl:
data2.jsonl：
data3.jsonl:
让我们尝试对这 3 个文件进行 schema 推断：
Query
Response
正如我们所见，来自文件 data3.jsonl 的 field3 并没有被推断出来。 这是因为 ClickHouse 首先尝试从文件 data1.jsonl 推断 schema，但由于字段 field2 的值全都是 NULL 而失败； 随后又尝试从 data2.jsonl 推断 schema 并成功，因此没有读取文件 data3.jsonl 中的数据。

​
Union 模式

在 Union 模式下，ClickHouse 假设各个文件的 schema 可能不同，因此会推断所有文件的 schema，再将它们合并成一个统一的 schema。 假设我们有 3 个文件 data1.jsonl、data2.jsonl 和 data3.jsonl，内容如下： data1.jsonl:
data2.jsonl:
data3.jsonl：
让我们尝试对这 3 个文件进行 schema 推断：
Query
Response
可以看到，我们得到了所有文件中的全部字段。 注意：
  • 由于某些文件可能不包含结果 schema 中的某些列，union mode 仅支持能够读取部分列的格式 (如 JSONEachRow、Parquet、TSVWithNames 等) ，对于其他格式 (如 CSV、TSV、JSONCompactEachRow 等) 则不起作用。
  • 如果 ClickHouse 无法从某个文件中推断出 schema，则会抛出异常。
  • 如果文件很多，从所有文件中读取 schema 可能会耗费较长时间。

​
自动检测格式

如果未指定数据格式，且无法通过文件扩展名判断，ClickHouse 会尝试根据文件内容检测其格式。 示例： 假设我们有一个 data 文件，其内容如下：
我们可以在不指定格式或结构的情况下查看并查询这个文件：
ClickHouse 只能识别部分格式，而且这种识别需要一定时间，因此最好始终明确指定格式。
最后修改于 2026年7月3日