> ## 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. > 介绍 ClickHouse 中从输入数据自动推断 schema 的页面 # 从输入数据自动推断 schema ClickHouse 几乎可以自动确定所有受支持的[输入格式](/zh/reference/formats)的输入数据结构。 本文将介绍何时会使用 schema 推断、它在不同输入格式下如何工作，以及可用于控制它的设置。
## 用法
当 ClickHouse 需要以特定数据格式读取数据，而其结构未知时，就会使用 schema 推断。
## 表函数 [file](/zh/reference/functions/table-functions/file), [s3](/zh/reference/functions/table-functions/s3), [url](/zh/reference/functions/table-functions/url), [hdfs](/zh/reference/functions/table-functions/hdfs), [azureBlobStorage](/zh/reference/functions/table-functions/azureBlobStorage).
这些表函数都支持可选参数 `structure`，用于指定输入数据的结构。如果未指定该参数，或将其设置为 `auto`，则会根据数据自动推断结构。 **示例：** 假设 `user_files` 目录中有一个采用 JSONEachRow 格式的文件 `hobbies.jsonl`，内容如下： ```json theme={null} {"id" : 1, "age" : 25, "name" : "Josh", "hobbies" : ["football", "cooking", "music"]} {"id" : 2, "age" : 19, "name" : "Alan", "hobbies" : ["tennis", "art"]} {"id" : 3, "age" : 32, "name" : "Lana", "hobbies" : ["fitness", "reading", "shopping"]} {"id" : 4, "age" : 47, "name" : "Brayan", "hobbies" : ["movies", "skydiving"]} ``` ClickHouse 无需指定其结构，即可读取这些数据： ```sql theme={null} SELECT * FROM file('hobbies.jsonl') ``` ```response theme={null} ┌─id─┬─age─┬─name───┬─hobbies──────────────────────────┐ │ 1 │ 25 │ Josh │ ['football','cooking','music'] │ │ 2 │ 19 │ Alan │ ['tennis','art'] │ │ 3 │ 32 │ Lana │ ['fitness','reading','shopping'] │ │ 4 │ 47 │ Brayan │ ['movies','skydiving'] │ └────┴─────┴────────┴──────────────────────────────────┘ ``` 注意：格式 `JSONEachRow` 是根据文件扩展名 `.jsonl` 自动识别的。 你可以使用 `DESCRIBE` 查询来查看自动识别的结构： ```sql theme={null} DESCRIBE file('hobbies.jsonl') ``` ```response theme={null} ┌─name────┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ id │ Nullable(Int64) │ │ │ │ │ │ │ age │ Nullable(Int64) │ │ │ │ │ │ │ name │ Nullable(String) │ │ │ │ │ │ │ hobbies │ Array(Nullable(String)) │ │ │ │ │ │ └─────────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
## 表引擎 [File](/zh/reference/engines/table-engines/special/file), [S3](/zh/reference/engines/table-engines/integrations/s3), [URL](/zh/reference/engines/table-engines/special/url), [HDFS](/zh/reference/engines/table-engines/integrations/hdfs), [azureBlobStorage](/zh/reference/engines/table-engines/integrations/azureBlobStorage)
如果在 `CREATE TABLE` 查询中未指定列列表，系统会自动根据数据推断表结构。 **示例：** 我们使用文件 `hobbies.jsonl`。可以创建一个使用 `File` 引擎的表，并读取该文件中的数据： ```sql theme={null} CREATE TABLE hobbies ENGINE=File(JSONEachRow, 'hobbies.jsonl') ``` ```response theme={null} Ok. ``` ```sql theme={null} SELECT * FROM hobbies ``` ```response theme={null} ┌─id─┬─age─┬─name───┬─hobbies──────────────────────────┐ │ 1 │ 25 │ Josh │ ['football','cooking','music'] │ │ 2 │ 19 │ Alan │ ['tennis','art'] │ │ 3 │ 32 │ Lana │ ['fitness','reading','shopping'] │ │ 4 │ 47 │ Brayan │ ['movies','skydiving'] │ └────┴─────┴────────┴──────────────────────────────────┘ ``` ```sql theme={null} DESCRIBE TABLE hobbies ``` ```response theme={null} ┌─name────┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ id │ Nullable(Int64) │ │ │ │ │ │ │ age │ Nullable(Int64) │ │ │ │ │ │ │ name │ Nullable(String) │ │ │ │ │ │ │ hobbies │ Array(Nullable(String)) │ │ │ │ │ │ └─────────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
## clickhouse-local
`clickhouse-local` 提供可选参数 `-S/--structure`，用于指定输入数据的结构。如果未指定该参数，或将其设为 `auto`，则会根据数据自动推断其结构。 **示例：** 以文件 `hobbies.jsonl` 为例。我们可以使用 `clickhouse-local` 查询该文件中的数据： ```shell theme={null} clickhouse-local --file='hobbies.jsonl' --table='hobbies' --query='DESCRIBE TABLE hobbies' ``` ```response theme={null} id Nullable(Int64) age Nullable(Int64) name Nullable(String) hobbies Array(Nullable(String)) ``` ```shell theme={null} clickhouse-local --file='hobbies.jsonl' --table='hobbies' --query='SELECT * FROM hobbies' ``` ```response theme={null} 1 25 Josh ['football','cooking','music'] 2 19 Alan ['tennis','art'] 3 32 Lana ['fitness','reading','shopping'] 4 47 Brayan ['movies','skydiving'] ```
## 使用插入表的结构
当使用表函数 `file/s3/url/hdfs` 向表中插入数据时， 可以选择使用插入表的结构，而不是从数据中提取结构。 这样可以提升插入性能，因为 schema 推断 可能会耗费一些时间。此外，当表具有优化后的 schema 时，这种方式也很有帮助，因此 无需执行类型转换。 有一个特殊设置 [use\_structure\_from\_insertion\_table\_in\_table\_functions](/zh/reference/settings/session-settings#use_structure_from_insertion_table_in_table_functions) 用于控制此行为。它有 3 个可能的值： * 0 - 表函数将从数据中提取结构。 * 1 - 表函数将使用插入表的结构。 * 2 - ClickHouse 将自动判断是否可以使用插入表的结构，或使用 schema 推断。默认值。 **示例 1：** 让我们创建一个具有以下结构的表 `hobbies1`： ```sql theme={null} CREATE TABLE hobbies1 ( `id` UInt64, `age` LowCardinality(UInt8), `name` String, `hobbies` Array(String) ) ENGINE = MergeTree ORDER BY id; ``` 并从文件 `hobbies.jsonl` 中插入数据： ```sql theme={null} INSERT INTO hobbies1 SELECT * FROM file(hobbies.jsonl) ``` 在这种情况下，文件中的所有列都会不作修改地插入表中，因此 ClickHouse 会使用插入表的结构，而不是进行 schema 推断。 **示例 2：** 创建具有以下结构的表 `hobbies2`： ```sql theme={null} CREATE TABLE hobbies2 ( `id` UInt64, `age` LowCardinality(UInt8), `hobbies` Array(String) ) ENGINE = MergeTree ORDER BY id; ``` 并从 `hobbies.jsonl` 文件中插入数据： ```sql theme={null} INSERT INTO hobbies2 SELECT id, age, hobbies FROM file(hobbies.jsonl) ``` 在这种情况下，`SELECT` 查询中的所有列都存在于该表中，因此 ClickHouse 将使用插入表的结构。 请注意，这仅适用于支持读取部分列的输入格式，例如 JSONEachRow、TSKV、Parquet 等 (因此例如 TSV 格式就不适用) 。 **示例 3：** 让我们创建表 `hobbies3`，其结构如下： ```sql theme={null} CREATE TABLE hobbies3 ( `identifier` UInt64, `age` LowCardinality(UInt8), `hobbies` Array(String) ) ENGINE = MergeTree ORDER BY identifier; ``` 并从 `hobbies.jsonl` 文件中插入数据： ```sql theme={null} INSERT INTO hobbies3 SELECT id, age, hobbies FROM file(hobbies.jsonl) ``` 在这种情况下，`SELECT` 查询中使用了列 `id`，但该表并没有这一列 (而是有一个名为 `identifier` 的列) ， 因此 ClickHouse 无法使用插入表的结构，而会使用 schema 推断。 **示例 4：** 让我们创建表 `hobbies4`，其结构如下： ```sql theme={null} CREATE TABLE hobbies4 ( `id` UInt64, `any_hobby` Nullable(String) ) ENGINE = MergeTree ORDER BY id; ``` 然后从文件 `hobbies.jsonl` 插入数据： ```sql theme={null} INSERT INTO hobbies4 SELECT id, empty(hobbies) ? NULL : hobbies[1] FROM file(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](/zh/reference/system-tables/schema_inference_cache)，其中包含当前缓存中的所有 schema，以及系统查询 `SYSTEM CLEAR SCHEMA CACHE [FOR File/S3/URL/HDFS]` 它可用于清理所有来源的 schema 缓存，或某个特定来源的 schema 缓存。 **示例：** 让我们尝试从 s3 中的样本数据集 `github-2022.ndjson.gz` 推断其结构，并看看 schema 推断缓存是如何工作的： ```sql theme={null} DESCRIBE TABLE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/github/github-2022.ndjson.gz') ``` ```response theme={null} ┌─name───────┬─type─────────────────────────────────────────┐ │ type │ Nullable(String) │ │ actor │ Tuple( ↴│ │ │↳ avatar_url Nullable(String), ↴│ │ │↳ display_login Nullable(String), ↴│ │ │↳ id Nullable(Int64), ↴│ │ │↳ login Nullable(String), ↴│ │ │↳ url Nullable(String)) │ │ repo │ Tuple( ↴│ │ │↳ id Nullable(Int64), ↴│ │ │↳ name Nullable(String), ↴│ │ │↳ url Nullable(String)) │ │ created_at │ Nullable(String) │ │ payload │ Tuple( ↴│ │ │↳ action Nullable(String), ↴│ │ │↳ distinct_size Nullable(Int64), ↴│ │ │↳ pull_request Tuple( ↴│ │ │↳ author_association Nullable(String),↴│ │ │↳ base Tuple( ↴│ │ │↳ ref Nullable(String), ↴│ │ │↳ sha Nullable(String)), ↴│ │ │↳ head Tuple( ↴│ │ │↳ ref Nullable(String), ↴│ │ │↳ sha Nullable(String)), ↴│ │ │↳ number Nullable(Int64), ↴│ │ │↳ state Nullable(String), ↴│ │ │↳ title Nullable(String), ↴│ │ │↳ updated_at Nullable(String), ↴│ │ │↳ user Tuple( ↴│ │ │↳ login Nullable(String))), ↴│ │ │↳ ref Nullable(String), ↴│ │ │↳ ref_type Nullable(String), ↴│ │ │↳ size Nullable(Int64)) │ └────────────┴──────────────────────────────────────────────┘ 5 rows in set. Elapsed: 0.601 sec. ``` ```sql theme={null} DESCRIBE TABLE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/github/github-2022.ndjson.gz') ``` ```response theme={null} ┌─name───────┬─type─────────────────────────────────────────┐ │ type │ Nullable(String) │ │ actor │ Tuple( ↴│ │ │↳ avatar_url Nullable(String), ↴│ │ │↳ display_login Nullable(String), ↴│ │ │↳ id Nullable(Int64), ↴│ │ │↳ login Nullable(String), ↴│ │ │↳ url Nullable(String)) │ │ repo │ Tuple( ↴│ │ │↳ id Nullable(Int64), ↴│ │ │↳ name Nullable(String), ↴│ │ │↳ url Nullable(String)) │ │ created_at │ Nullable(String) │ │ payload │ Tuple( ↴│ │ │↳ action Nullable(String), ↴│ │ │↳ distinct_size Nullable(Int64), ↴│ │ │↳ pull_request Tuple( ↴│ │ │↳ author_association Nullable(String),↴│ │ │↳ base Tuple( ↴│ │ │↳ ref Nullable(String), ↴│ │ │↳ sha Nullable(String)), ↴│ │ │↳ head Tuple( ↴│ │ │↳ ref Nullable(String), ↴│ │ │↳ sha Nullable(String)), ↴│ │ │↳ number Nullable(Int64), ↴│ │ │↳ state Nullable(String), ↴│ │ │↳ title Nullable(String), ↴│ │ │↳ updated_at Nullable(String), ↴│ │ │↳ user Tuple( ↴│ │ │↳ login Nullable(String))), ↴│ │ │↳ ref Nullable(String), ↴│ │ │↳ ref_type Nullable(String), ↴│ │ │↳ size Nullable(Int64)) │ └────────────┴──────────────────────────────────────────────┘ 5 行，耗时 0.059 秒。 ``` 如你所见，第二个查询几乎瞬间就成功了。 下面我们尝试更改一些可能影响推断 schema 的设置： ```sql theme={null} DESCRIBE TABLE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/github/github-2022.ndjson.gz') SETTINGS input_format_json_try_infer_named_tuples_from_objects=0, input_format_json_read_objects_as_strings = 1 ┌─name───────┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ type │ Nullable(String) │ │ │ │ │ │ │ actor │ Nullable(String) │ │ │ │ │ │ │ repo │ Nullable(String) │ │ │ │ │ │ │ created_at │ Nullable(String) │ │ │ │ │ │ │ payload │ Nullable(String) │ │ │ │ │ │ └────────────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ 5 rows in set. Elapsed: 0.611 sec ``` 如你所见，对于同一个文件，并未使用缓存中的 schema，因为会影响 schema 推断的设置已发生更改。 让我们查看 `system.schema_inference_cache` 表中的内容： ```sql theme={null} SELECT schema, format, source FROM system.schema_inference_cache WHERE storage='S3' ``` ```response theme={null} ┌─schema──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─format─┬─source───────────────────────────────────────────────────────────────────────────────────────────────────┐ │ type Nullable(String), actor Tuple(avatar_url Nullable(String), display_login Nullable(String), id Nullable(Int64), login Nullable(String), url Nullable(String)), repo Tuple(id Nullable(Int64), name Nullable(String), url Nullable(String)), created_at Nullable(String), payload Tuple(action Nullable(String), distinct_size Nullable(Int64), pull_request Tuple(author_association Nullable(String), base Tuple(ref Nullable(String), sha Nullable(String)), head Tuple(ref Nullable(String), sha Nullable(String)), number Nullable(Int64), state Nullable(String), title Nullable(String), updated_at Nullable(String), user Tuple(login Nullable(String))), ref Nullable(String), ref_type Nullable(String), size Nullable(Int64)) │ NDJSON │ datasets-documentation.s3.eu-west-3.amazonaws.com443/datasets-documentation/github/github-2022.ndjson.gz │ │ type Nullable(String), actor Nullable(String), repo Nullable(String), created_at Nullable(String), payload Nullable(String) │ NDJSON │ datasets-documentation.s3.eu-west-3.amazonaws.com443/datasets-documentation/github/github-2022.ndjson.gz │ └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ``` 如你所见，同一个文件对应两种不同的 schema。 我们可以使用系统查询清除 schema 缓存： ```sql theme={null} SYSTEM CLEAR SCHEMA CACHE FOR S3 ``` ```response theme={null} Ok. ``` ```sql theme={null} SELECT count() FROM system.schema_inference_cache WHERE storage='S3' ``` ```response theme={null} ┌─count()─┐ │ 0 │ └─────────┘ ```
## 文本格式
对于文本格式，ClickHouse 会按行读取数据，根据格式提取列值， 然后使用一些递归解析器和启发式规则来确定每个值的类型。在 schema 推断中，从数据中读取的最大行数和字节数 由设置 `input_format_max_rows_to_read_for_schema_inference` (默认值为 25000) 和 `input_format_max_bytes_to_read_for_schema_inference` (默认值为 32Mb) 控制。 默认情况下，所有推断出的类型均为 [Nullable](/zh/reference/data-types/nullable)，但你可以通过设置 `schema_inference_make_columns_nullable` 更改这一行为 (请参见[设置](#settings-for-text-formats)部分中的示例) 。
### JSON 格式
在 JSON 格式中，ClickHouse 会按照 JSON 规范解析值，并尝试为其推断最合适的数据类型。 下面介绍其工作原理、可推断的类型，以及在 JSON formats 中可使用的特定设置。 **示例** 在本节及后续内容中，示例将使用 [format](/zh/reference/functions/table-functions/format) 表函数。 整数、浮点数、Bool、String： ```sql theme={null} DESC format(JSONEachRow, '{"int" : 42, "float" : 42.42, "string" : "Hello, World!"}'); ``` ```response theme={null} ┌─name───┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ int │ Nullable(Int64) │ │ │ │ │ │ │ float │ Nullable(Float64) │ │ │ │ │ │ │ bool │ Nullable(Bool) │ │ │ │ │ │ │ string │ Nullable(String) │ │ │ │ │ │ └────────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 日期、日期时间： ```sql theme={null} DESC format(JSONEachRow, '{"date" : "2022-01-01", "datetime" : "2022-01-01 00:00:00", "datetime64" : "2022-01-01 00:00:00.000"}') ``` ```response theme={null} ┌─name───────┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ date │ Nullable(Date) │ │ │ │ │ │ │ datetime │ Nullable(DateTime) │ │ │ │ │ │ │ datetime64 │ Nullable(DateTime64(9)) │ │ │ │ │ │ └────────────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` Arrays： ```sql theme={null} DESC format(JSONEachRow, '{"arr" : [1, 2, 3], "nested_arrays" : [[1, 2, 3], [4, 5, 6], []]}') ``` ```response theme={null} ┌─name──────────┬─type──────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ arr │ Array(Nullable(Int64)) │ │ │ │ │ │ │ nested_arrays │ Array(Array(Nullable(Int64))) │ │ │ │ │ │ └───────────────┴───────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果数组包含 `null`，ClickHouse 将根据其他数组元素来推断类型： ```sql theme={null} DESC format(JSONEachRow, '{"arr" : [null, 42, null]}') ``` ```response theme={null} ┌─name─┬─type───────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ arr │ Array(Nullable(Int64)) │ │ │ │ │ │ └──────┴────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果数组包含不同类型的值，且设置 `input_format_json_infer_array_of_dynamic_from_array_of_different_types` 已启用 (默认启用) ，则该数组的类型将为 `Array(Dynamic)`： ```sql theme={null} SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=1; DESC format(JSONEachRow, '{"arr" : [42, "hello", [1, 2, 3]]}'); ``` ```response theme={null} ┌─name─┬─type───────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ arr │ Array(Dynamic) │ │ │ │ │ │ └──────┴────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 命名元组： 当启用设置 `input_format_json_try_infer_named_tuples_from_objects` 时，ClickHouse 会在进行 schema 推断 期间尝试从 JSON 对象中推断命名元组。 生成的命名元组将包含样本数据中所有对应 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}}}') ``` ```response theme={null} ┌─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_infer_array_of_dynamic_from_array_of_different_types`，我们会在 JSON 格式中将元素类型不同的 Array 视为未命名元组。 ```sql theme={null} SET input_format_json_infer_array_of_dynamic_from_array_of_different_types = 0; DESC format(JSONEachRow, '{"tuple" : [1, "Hello, World!", [1, 2, 3]]}') ``` ```response theme={null} ┌─name──┬─type─────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ tuple │ Tuple(Nullable(Int64), Nullable(String), Array(Nullable(Int64))) │ │ │ │ │ │ └───────┴──────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果某些值为 `null` 或为空，则使用其他行中对应值的类型： ```sql theme={null} SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=0; DESC format(JSONEachRow, $$ {"tuple" : [1, null, null]} {"tuple" : [null, "Hello, World!", []]} {"tuple" : [null, null, [1, 2, 3]]} $$) ``` ```response theme={null} ┌─name──┬─type─────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ tuple │ Tuple(Nullable(Int64), Nullable(String), Array(Nullable(Int64))) │ │ │ │ │ │ └───────┴──────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` Map： 在 JSON 中，可以将值类型相同的对象读取为 Map 类型。 注意：只有在禁用设置 `input_format_json_read_objects_as_strings` 和 `input_format_json_try_infer_named_tuples_from_objects` 时，此功能才会生效。 ```sql theme={null} SET input_format_json_read_objects_as_strings = 0, input_format_json_try_infer_named_tuples_from_objects = 0; DESC format(JSONEachRow, '{"map" : {"key1" : 42, "key2" : 24, "key3" : 4}}') ``` ```response theme={null} ┌─name─┬─type─────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ map │ Map(String, Nullable(Int64)) │ │ │ │ │ │ └──────┴──────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 嵌套复杂数据类型： ```sql theme={null} DESC format(JSONEachRow, '{"value" : [[[42, 24], []], {"key1" : 42, "key2" : 24}]}') ``` ```response theme={null} ┌─name──┬─type─────────────────────────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ value │ Tuple(Array(Array(Nullable(String))), Tuple(key1 Nullable(Int64), key2 Nullable(Int64))) │ │ │ │ │ │ └───────┴──────────────────────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果 ClickHouse 无法确定某个键的类型，例如数据中只包含 null/空对象/空数组，那么在启用设置 `input_format_json_infer_incomplete_types_as_strings` 时将使用 `String` 类型；否则会抛出异常： ```sql theme={null} DESC format(JSONEachRow, '{"arr" : [null, null]}') SETTINGS input_format_json_infer_incomplete_types_as_strings = 1; ``` ```response theme={null} ┌─name─┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ arr │ Array(Nullable(String)) │ │ │ │ │ │ └──────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} DESC format(JSONEachRow, '{"arr" : [null, null]}') SETTINGS input_format_json_infer_incomplete_types_as_strings = 0; ``` ```response theme={null} Code: 652. DB::Exception: Received from localhost:9000. DB::Exception: Cannot determine type for column 'arr' by first 1 rows of data, most likely this column contains only Nulls or empty Arrays/Maps. ... ```
#### JSON 设置
##### input\_format\_json\_try\_infer\_numbers\_from\_strings
启用此设置后，可以从字符串值中推断出数值。 此设置默认处于禁用状态。 **示例：** ```sql theme={null} SET input_format_json_try_infer_numbers_from_strings = 1; DESC format(JSONEachRow, $$ {"value" : "42"} {"value" : "424242424242"} $$) ``` ```response theme={null} ┌─name──┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ value │ Nullable(Int64) │ │ │ │ │ │ └───────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
##### input\_format\_json\_try\_infer\_named\_tuples\_from\_objects
启用此设置后，可以从 JSON 对象中推断命名元组。生成的命名元组将包含样本数据中所有对应 JSON 对象里的全部元素。 当 JSON 数据不是稀疏数据时，此设置会很有用，因为数据样本将包含所有可能的对象键。 此设置默认启用。 **示例** ```sql title="Query" 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}}}') ``` ```response title="Response" theme={null} ┌─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))) │ │ │ │ │ │ └──────┴────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql title="Query" theme={null} SET input_format_json_try_infer_named_tuples_from_objects = 1; DESC format(JSONEachRow, '{"array" : [{"a" : 42, "b" : "Hello"}, {}, {"c" : [1,2,3]}, {"d" : "2020-01-01"}]}') ``` ```markdown title="Response" theme={null} ┌─name──┬─type────────────────────────────────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ array │ Array(Tuple(a Nullable(Int64), b Nullable(String), c Array(Nullable(Int64)), d Nullable(Date))) │ │ │ │ │ │ └───────┴─────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
##### 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 对象读取为命名元组。 默认禁用。 **示例** 在该设置禁用时： ```sql title="Query" theme={null} SET input_format_json_try_infer_named_tuples_from_objects = 1; SET input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects = 0; DESC format(JSONEachRow, '{"obj" : {"a" : 42}}, {"obj" : {"a" : {"b" : "Hello"}}}'); ``` ```response title="Response" theme={null} Code: 636. DB::Exception: The table structure cannot be extracted from a JSONEachRow format file. Error: Code: 117. DB::Exception: JSON objects have ambiguous data: in some objects path 'a' has type 'Int64' and in some - 'Tuple(b String)'. You can enable setting input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects to use String type for path 'a'. (INCORRECT_DATA) (version 24.3.1.1). You can specify the structure manually. (CANNOT_EXTRACT_TABLE_STRUCTURE) ``` 启用此设置后： ```sql title="Query" theme={null} SET input_format_json_try_infer_named_tuples_from_objects = 1; SET input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects = 1; DESC format(JSONEachRow, '{"obj" : "a" : 42}, {"obj" : {"a" : {"b" : "Hello"}}}'); SELECT * FROM format(JSONEachRow, '{"obj" : {"a" : 42}}, {"obj" : {"a" : {"b" : "Hello"}}}'); ``` ```response title="Response" theme={null} ┌─name─┬─type──────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ obj │ Tuple(a Nullable(String)) │ │ │ │ │ │ └──────┴───────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ┌─obj─────────────────┐ │ ('42') │ │ ('{"b" : "Hello"}') │ └─────────────────────┘ ```
##### input\_format\_json\_read\_objects\_as\_strings
启用此设置后，可以将嵌套 JSON 对象读取为字符串。 此设置可用于在不使用 JSON object 类型的情况下读取嵌套 JSON 对象。 此设置默认已启用。 注意：只有在禁用 `input_format_json_try_infer_named_tuples_from_objects` 设置时，启用此设置才会生效。 ```sql theme={null} SET input_format_json_read_objects_as_strings = 1, input_format_json_try_infer_named_tuples_from_objects = 0; DESC format(JSONEachRow, $$ {"obj" : {"key1" : 42, "key2" : [1,2,3,4]}} {"obj" : {"key3" : {"nested_key" : 1}}} $$) ``` ```response theme={null} ┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ obj │ Nullable(String) │ │ │ │ │ │ └──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
##### input\_format\_json\_read\_numbers\_as\_strings
启用此设置后，可将数值读取为字符串。 此设置默认启用。 **示例** ```sql theme={null} SET input_format_json_read_numbers_as_strings = 1; DESC format(JSONEachRow, $$ {"value" : 1055} {"value" : "unknown"} $$) ``` ```response theme={null} ┌─name──┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ value │ Nullable(String) │ │ │ │ │ │ └───────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
##### input\_format\_json\_read\_bools\_as\_numbers
启用此设置后，可以将 Bool 值按数值读取。 此设置默认启用。 **示例：** ```sql theme={null} SET input_format_json_read_bools_as_numbers = 1; DESC format(JSONEachRow, $$ {"value" : true} {"value" : 42} $$) ``` ```response theme={null} ┌─name──┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ value │ Nullable(Int64) │ │ │ │ │ │ └───────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
##### input\_format\_json\_read\_bools\_as\_strings
启用此设置后，可将 Bool 值按字符串读取。 此设置默认启用。 **示例：** ```sql theme={null} SET input_format_json_read_bools_as_strings = 1; DESC format(JSONEachRow, $$ {"value" : true} {"value" : "Hello, World"} $$) ``` ```response theme={null} ┌─name──┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ value │ Nullable(String) │ │ │ │ │ │ └───────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
##### input\_format\_json\_read\_arrays\_as\_strings
启用此设置后，可以将 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]]}'); ``` ```response theme={null} ┌─arr───────────────────┬─toTypeName(arr)─┬─arrayElement(JSONExtractArrayRaw(arr), 3)─┐ │ [1, "Hello", [1,2,3]] │ String │ [1,2,3] │ └───────────────────────┴─────────────────┴───────────────────────────────────────────┘ ```
##### 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： ```sql title="Query" 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" : []}}'); ``` ```markdown title="Response" theme={null} ┌─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,'{}',[]) │ └────────────────────────────────┘ ```
### 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 时尝试检测包含列名 (以及可能包含类型) 的表头。该设置默认启用。 **示例：** 整数、浮点数、布尔值、字符串： ```sql theme={null} DESC format(CSV, '42,42.42,true,"Hello,World!"') ``` ```response theme={null} ┌─name─┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Int64) │ │ │ │ │ │ │ c2 │ Nullable(Float64) │ │ │ │ │ │ │ c3 │ Nullable(Bool) │ │ │ │ │ │ │ c4 │ Nullable(String) │ │ │ │ │ │ └──────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 未加引号的字符串： ```sql theme={null} DESC format(CSV, 'Hello world!,World hello!') ``` ```response theme={null} ┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(String) │ │ │ │ │ │ │ c2 │ Nullable(String) │ │ │ │ │ │ └──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 日期、日期时间： ```sql theme={null} DESC format(CSV, '"2020-01-01","2020-01-01 00:00:00","2022-01-01 00:00:00.000"') ``` ```response theme={null} ┌─name─┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Date) │ │ │ │ │ │ │ c2 │ Nullable(DateTime) │ │ │ │ │ │ │ c3 │ Nullable(DateTime64(9)) │ │ │ │ │ │ └──────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 数组： ```sql theme={null} DESC format(CSV, '"[1,2,3]","[[1, 2], [], [3, 4]]"') ``` ```response theme={null} ┌─name─┬─type──────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Nullable(Int64)) │ │ │ │ │ │ │ c2 │ Array(Array(Nullable(Int64))) │ │ │ │ │ │ └──────┴───────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} DESC format(CSV, $$"['Hello', 'world']","[['Abc', 'Def'], []]"$$) ``` ```response theme={null} ┌─name─┬─type───────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Nullable(String)) │ │ │ │ │ │ │ c2 │ Array(Array(Nullable(String))) │ │ │ │ │ │ └──────┴────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果数组中包含 NULL，ClickHouse 将使用该数组中其他元素的类型： ```sql theme={null} DESC format(CSV, '"[NULL, 42, NULL]"') ``` ```response theme={null} ┌─name─┬─type───────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Nullable(Int64)) │ │ │ │ │ │ └──────┴────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` Map： ```sql theme={null} DESC format(CSV, $$"{'key1' : 42, 'key2' : 24}"$$) ``` ```response theme={null} ┌─name─┬─type─────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Map(String, Nullable(Int64)) │ │ │ │ │ │ └──────┴──────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 嵌套 数组 和 Map： ```sql theme={null} DESC format(CSV, $$"[{'key1' : [[42, 42], []], 'key2' : [[null], [42]]}]"$$) ``` ```response theme={null} ┌─name─┬─type──────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Map(String, Array(Array(Nullable(Int64))))) │ │ │ │ │ │ └──────┴───────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果 ClickHouse 因数据仅包含 null 值而无法确定引号内的类型，就会将其视为 String： ```sql theme={null} DESC format(CSV, '"[NULL, NULL]"') ``` ```response theme={null} ┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(String) │ │ │ │ │ │ └──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 禁用 `input_format_csv_use_best_effort_in_schema_inference` 设置的示例： ```sql theme={null} SET input_format_csv_use_best_effort_in_schema_inference = 0 DESC format(CSV, '"[1,2,3]",42.42,Hello World!') ``` ```response theme={null} ┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(String) │ │ │ │ │ │ │ c2 │ Nullable(String) │ │ │ │ │ │ │ c3 │ Nullable(String) │ │ │ │ │ │ └──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 表头自动检测示例 (启用 `input_format_csv_detect_header` 时) ： 仅列名： ```sql theme={null} SELECT * FROM format(CSV, $$"number","string","array" 42,"Hello","[1, 2, 3]" 43,"World","[4, 5, 6]" $$) ``` ```response theme={null} ┌─number─┬─string─┬─array───┐ │ 42 │ Hello │ [1,2,3] │ │ 43 │ World │ [4,5,6] │ └────────┴────────┴─────────┘ ``` 名称和类型： ```sql theme={null} DESC format(CSV, $$"number","string","array" "UInt32","String","Array(UInt16)" 42,"Hello","[1, 2, 3]" 43,"World","[4, 5, 6]" $$) ``` ```response theme={null} ┌─name───┬─type──────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ number │ UInt32 │ │ │ │ │ │ │ string │ String │ │ │ │ │ │ │ array │ Array(UInt16) │ │ │ │ │ │ └────────┴───────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 请注意，只有在至少有一列不是 String 类型时，才能检测到表头。如果所有列都是 String 类型，则无法检测到表头： ```sql theme={null} SELECT * FROM format(CSV, $$"first_column","second_column" "Hello","World" "World","Hello" $$) ``` ```response theme={null} ┌─c1───────────┬─c2────────────┐ │ first_column │ second_column │ │ Hello │ World │ │ World │ Hello │ └──────────────┴───────────────┘ ```
#### CSV 设置
##### input\_format\_csv\_try\_infer\_numbers\_from\_strings
启用此设置后，可以从字符串值中推断数值。 此设置默认禁用。 **示例：** ```sql theme={null} SET input_format_json_try_infer_numbers_from_strings = 1; DESC format(CSV, '42,42.42'); ``` ```response theme={null} ┌─name─┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Int64) │ │ │ │ │ │ │ c2 │ Nullable(Float64) │ │ │ │ │ │ └──────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
### 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 时尝试检测包含列名 (以及可能还有类型) 的表头。此设置默认启用。 **示例：** 整数、浮点数、布尔值、字符串： ```sql theme={null} DESC format(TSV, '42 42.42 true Hello,World!') ``` ```response theme={null} ┌─name─┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Int64) │ │ │ │ │ │ │ c2 │ Nullable(Float64) │ │ │ │ │ │ │ c3 │ Nullable(Bool) │ │ │ │ │ │ │ c4 │ Nullable(String) │ │ │ │ │ │ └──────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} DESC format(TSKV, 'int=42 float=42.42 bool=true string=Hello,World!\n') ``` ```response theme={null} ┌─name───┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ int │ Nullable(Int64) │ │ │ │ │ │ │ float │ Nullable(Float64) │ │ │ │ │ │ │ bool │ Nullable(Bool) │ │ │ │ │ │ │ string │ Nullable(String) │ │ │ │ │ │ └────────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 日期、日期时间： ```sql theme={null} DESC format(TSV, '2020-01-01 2020-01-01 00:00:00 2022-01-01 00:00:00.000') ``` ```response theme={null} ┌─name─┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Date) │ │ │ │ │ │ │ c2 │ Nullable(DateTime) │ │ │ │ │ │ │ c3 │ Nullable(DateTime64(9)) │ │ │ │ │ │ └──────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 数组： ```sql theme={null} DESC format(TSV, '[1,2,3] [[1, 2], [], [3, 4]]') ``` ```response theme={null} ┌─name─┬─type──────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Nullable(Int64)) │ │ │ │ │ │ │ c2 │ Array(Array(Nullable(Int64))) │ │ │ │ │ │ └──────┴───────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} DESC format(TSV, '[''Hello'', ''world''] [[''Abc'', ''Def''], []]') ``` ```response theme={null} ┌─name─┬─type───────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Nullable(String)) │ │ │ │ │ │ │ c2 │ Array(Array(Nullable(String))) │ │ │ │ │ │ └──────┴────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果数组包含 null 值，ClickHouse 将使用数组中其他元素的类型： ```sql theme={null} DESC format(TSV, '[NULL, 42, NULL]') ``` ```response theme={null} ┌─name─┬─type───────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Nullable(Int64)) │ │ │ │ │ │ └──────┴────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` Tuples： ```sql theme={null} DESC format(TSV, $$(42, 'Hello, world!')$$) ``` ```response theme={null} ┌─name─┬─type─────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Tuple(Nullable(Int64), Nullable(String)) │ │ │ │ │ │ └──────┴──────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` Map： ```sql theme={null} DESC format(TSV, $${'key1' : 42, 'key2' : 24}$$) ``` ```response theme={null} ┌─name─┬─type─────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Map(String, Nullable(Int64)) │ │ │ │ │ │ └──────┴──────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 嵌套数组、Tuple 和 Map： ```sql theme={null} DESC format(TSV, $$[{'key1' : [(42, 'Hello'), (24, NULL)], 'key2' : [(NULL, ','), (42, 'world!')]}]$$) ``` ```response theme={null} ┌─name─┬─type────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Map(String, Array(Tuple(Nullable(Int64), Nullable(String))))) │ │ │ │ │ │ └──────┴─────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果 ClickHouse 无法确定类型 (因为数据仅包含 NULL 值) ，ClickHouse 会将其视为 String： ```sql theme={null} DESC format(TSV, '[NULL, NULL]') ``` ```response theme={null} ┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(String) │ │ │ │ │ │ └──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 禁用 `input_format_tsv_use_best_effort_in_schema_inference` 设置的示例： ```sql theme={null} SET input_format_tsv_use_best_effort_in_schema_inference = 0 DESC format(TSV, '[1,2,3] 42.42 Hello World!') ``` ```response theme={null} ┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(String) │ │ │ │ │ │ │ c2 │ Nullable(String) │ │ │ │ │ │ │ c3 │ Nullable(String) │ │ │ │ │ │ └──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 表头自动检测示例 (启用 `input_format_tsv_detect_header` 时) ： 仅列名： ```sql theme={null} SELECT * FROM format(TSV, $$number string array 42 Hello [1, 2, 3] 43 World [4, 5, 6] $$); ``` ```response theme={null} ┌─number─┬─string─┬─array───┐ │ 42 │ Hello │ [1,2,3] │ │ 43 │ World │ [4,5,6] │ └────────┴────────┴─────────┘ ``` 名称和类型： ```sql theme={null} DESC format(TSV, $$number string array UInt32 String Array(UInt16) 42 Hello [1, 2, 3] 43 World [4, 5, 6] $$) ``` ```response theme={null} ┌─name───┬─type──────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ number │ UInt32 │ │ │ │ │ │ │ string │ String │ │ │ │ │ │ │ array │ Array(UInt16) │ │ │ │ │ │ └────────┴───────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 请注意，只有在至少有一列不是 String 类型时，才能识别表头。如果所有列都是 String 类型，则无法识别表头： ```sql theme={null} SELECT * FROM format(TSV, $$first_column second_column Hello World World Hello $$) ``` ```response theme={null} ┌─c1───────────┬─c2────────────┐ │ first_column │ second_column │ │ Hello │ World │ │ World │ Hello │ └──────────────┴───────────────┘ ```
### 值
在 Values 格式中，ClickHouse 从行中提取列值，然后使用递归解析器对其进行解析，解析方式与字面量的解析方式类似。 **示例：** 整数、浮点数、Bool、String： ```sql theme={null} DESC format(Values, $$(42, 42.42, true, 'Hello,World!')$$) ``` ```response theme={null} ┌─name─┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Int64) │ │ │ │ │ │ │ c2 │ Nullable(Float64) │ │ │ │ │ │ │ c3 │ Nullable(Bool) │ │ │ │ │ │ │ c4 │ Nullable(String) │ │ │ │ │ │ └──────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 日期、日期时间： ```sql theme={null} DESC format(Values, $$('2020-01-01', '2020-01-01 00:00:00', '2022-01-01 00:00:00.000')$$) ``` ```response theme={null} ┌─name─┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Date) │ │ │ │ │ │ │ c2 │ Nullable(DateTime) │ │ │ │ │ │ │ c3 │ Nullable(DateTime64(9)) │ │ │ │ │ │ └──────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` Arrays (数组) ： ```sql theme={null} DESC format(Values, '([1,2,3], [[1, 2], [], [3, 4]])') ``` ```response theme={null} ┌─name─┬─type──────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Nullable(Int64)) │ │ │ │ │ │ │ c2 │ Array(Array(Nullable(Int64))) │ │ │ │ │ │ └──────┴───────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果数组中包含 null，ClickHouse 将根据其他数组元素来推断类型： ```sql theme={null} DESC format(Values, '([NULL, 42, NULL])') ``` ```response theme={null} ┌─name─┬─type───────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Nullable(Int64)) │ │ │ │ │ │ └──────┴────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 元组： ```sql theme={null} DESC format(Values, $$((42, 'Hello, world!'))$$) ``` ```response theme={null} ┌─name─┬─type─────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Tuple(Nullable(Int64), Nullable(String)) │ │ │ │ │ │ └──────┴──────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` Map： ```sql theme={null} DESC format(Values, $$({'key1' : 42, 'key2' : 24})$$) ``` ```response theme={null} ┌─name─┬─type─────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Map(String, Nullable(Int64)) │ │ │ │ │ │ └──────┴──────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 嵌套的 Array、Tuple 和 Map： ```sql theme={null} DESC format(Values, $$([{'key1' : [(42, 'Hello'), (24, NULL)], 'key2' : [(NULL, ','), (42, 'world!')]}])$$) ``` ```response theme={null} ┌─name─┬─type────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Array(Map(String, Array(Tuple(Nullable(Int64), Nullable(String))))) │ │ │ │ │ │ └──────┴─────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 如果 ClickHouse 无法确定类型 (因为数据仅包含 NULL) ，则会抛出异常： ```sql theme={null} DESC format(Values, '([NULL, NULL])') ``` ```response theme={null} Code: 652. DB::Exception: Received from localhost:9000. DB::Exception: Cannot determine type for column 'c1' by first 1 rows of data, most likely this column contains only Nulls or empty Arrays/Maps. ... ``` 禁用 `input_format_tsv_use_best_effort_in_schema_inference` 设置的示例： ```sql theme={null} SET input_format_tsv_use_best_effort_in_schema_inference = 0 DESC format(TSV, '[1,2,3] 42.42 Hello World!') ``` ```response theme={null} ┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(String) │ │ │ │ │ │ │ c2 │ Nullable(String) │ │ │ │ │ │ │ c3 │ Nullable(String) │ │ │ │ │ │ └──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
### CustomSeparated
在 CustomSeparated 格式中，ClickHouse 会先根据指定的分隔符从每一行中提取所有列值，然后再根据转义规则尝试推断每个值的数据类型。 如果启用了设置 `input_format_custom_detect_header`，ClickHouse 会在推断 schema 时尝试检测包含列名 (以及可能还包含类型) 的表头。此设置默认启用。 **示例** ```sql theme={null} SET format_custom_row_before_delimiter = '', format_custom_row_after_delimiter = '\n', format_custom_row_between_delimiter = '\n', format_custom_result_before_delimiter = '\n', format_custom_result_after_delimiter = '\n', format_custom_field_delimiter = '', format_custom_escaping_rule = 'Quoted' DESC format(CustomSeparated, $$ 42.42'Some string 1'[1, NULL, 3] NULL'Some string 3'[1, 2, NULL] $$) ``` ```response theme={null} ┌─name─┬─type───────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Float64) │ │ │ │ │ │ │ c2 │ Nullable(String) │ │ │ │ │ │ │ c3 │ Array(Nullable(Int64)) │ │ │ │ │ │ └──────┴────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 表头自动检测示例 (启用 `input_format_custom_detect_header` 时) ： ```sql theme={null} SET format_custom_row_before_delimiter = '', format_custom_row_after_delimiter = '\n', format_custom_row_between_delimiter = '\n', format_custom_result_before_delimiter = '\n', format_custom_result_after_delimiter = '\n', format_custom_field_delimiter = '', format_custom_escaping_rule = 'Quoted' DESC format(CustomSeparated, $$ 'number''string''array' 42.42'Some string 1'[1, NULL, 3] NULL'Some string 3'[1, 2, NULL] $$) ``` ```response theme={null} ┌─number─┬─string────────┬─array──────┐ │ 42.42 │ Some string 1 │ [1,NULL,3] │ │ ᴺᵁᴸᴸ │ Some string 3 │ [1,2,NULL] │ └────────┴───────────────┴────────────┘ ```
### Template
在 Template 格式中，ClickHouse 会先按照指定模板从行中提取所有列值，然后再根据各自的转义规则尝试推断 每个值的数据类型。 **示例** 假设我们有一个名为 `resultset` 的文件，内容如下： ```bash theme={null} ${data} ``` 以及内容如下的文件 `row_format`： ```text theme={null} ${column_1:CSV}${column_2:Quoted}${column_3:JSON} ``` 接着我们可以执行以下查询： ```sql theme={null} SET format_template_rows_between_delimiter = '\n', format_template_row = 'row_format', format_template_resultset = 'resultset_format' DESC format(Template, $$ 42.42'Some string 1'[1, null, 2] \N'Some string 3'[1, 2, null] $$) ``` ```response theme={null} ┌─name─────┬─type───────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ column_1 │ Nullable(Float64) │ │ │ │ │ │ │ column_2 │ Nullable(String) │ │ │ │ │ │ │ column_3 │ Array(Nullable(Int64)) │ │ │ │ │ │ └──────────┴────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
### Regexp
与 Template 类似，在 Regexp 格式中，ClickHouse 会先根据指定的正则表达式从每一行中提取所有列值，再按照指定的转义规则尝试推断每个值的数据类型。 **示例** ```sql theme={null} SET format_regexp = '^Line: value_1=(.+?), value_2=(.+?), value_3=(.+?)', format_regexp_escaping_rule = 'CSV' DESC format(Regexp, $$Line: value_1=42, value_2="Some string 1", value_3="[1, NULL, 3]" Line: value_1=2, value_2="Some string 2", value_3="[4, 5, NULL]"$$) ``` ```response theme={null} ┌─name─┬─type───────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Int64) │ │ │ │ │ │ │ c2 │ Nullable(String) │ │ │ │ │ │ │ c3 │ Array(Nullable(Int64)) │ │ │ │ │ │ └──────┴────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
### 文本格式设置
#### 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,...`。 **示例** ```sql theme={null} DESC format(TSV, 'Hello, World! 42 [1, 2, 3]') settings column_names_for_schema_inference = 'str,int,arr' ``` ```response theme={null} ┌─name─┬─type───────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ str │ Nullable(String) │ │ │ │ │ │ │ int │ Nullable(Int64) │ │ │ │ │ │ │ arr │ Array(Nullable(Int64)) │ │ │ │ │ │ └──────┴────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
#### schema\_inference\_hints
在 schema 推断 中使用的列名和类型列表，用于替代自动推断出的类型。格式：'column\_name1 column\_type1, column\_name2 column\_type2, ...'。 此设置可用于指定无法自动推断出的列类型，或用于优化 schema。 **示例** ```sql theme={null} DESC format(JSONEachRow, '{"id" : 1, "age" : 25, "name" : "Josh", "status" : null, "hobbies" : ["football", "cooking"]}') SETTINGS schema_inference_hints = 'age LowCardinality(UInt8), status Nullable(String)', allow_suspicious_low_cardinality_types=1 ``` ```response theme={null} ┌─name────┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ id │ Nullable(Int64) │ │ │ │ │ │ │ age │ LowCardinality(UInt8) │ │ │ │ │ │ │ name │ Nullable(String) │ │ │ │ │ │ │ status │ Nullable(String) │ │ │ │ │ │ │ hobbies │ Array(Nullable(String)) │ │ │ │ │ │ └─────────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
#### schema\_inference\_make\_columns\_nullable \$
控制在对不含可空性信息的格式进行 schema inference 时，是否将推断出的类型设为 `Nullable`。可能的值： * 0 - 推断出的类型永远不会是 `Nullable`， * 1 - 所有推断类型都将为 `Nullable`， * 2 或 'auto' - 对于文本格式，仅当列在 schema 推断期间解析的样本中包含 `NULL` 时，推断出的类型才会是 `Nullable`；对于强类型格式 (Parquet、ORC、Arrow) ，可空性信息会从文件元数据中获取， * 3 - 对于文本格式，使用 `Nullable`；对于强类型格式，则使用文件元数据。 默认值：3。 **示例** ```sql theme={null} SET schema_inference_make_columns_nullable = 1; DESC format(JSONEachRow, $$ {"id" : 1, "age" : 25, "name" : "Josh", "status" : null, "hobbies" : ["football", "cooking"]} {"id" : 2, "age" : 19, "name" : "Alan", "status" : "married", "hobbies" : ["tennis", "art"]} $$) ``` ```response theme={null} ┌─name────┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ id │ Nullable(Int64) │ │ │ │ │ │ │ age │ Nullable(Int64) │ │ │ │ │ │ │ name │ Nullable(String) │ │ │ │ │ │ │ status │ Nullable(String) │ │ │ │ │ │ │ hobbies │ Array(Nullable(String)) │ │ │ │ │ │ └─────────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} SET schema_inference_make_columns_nullable = 'auto'; DESC format(JSONEachRow, $$ {"id" : 1, "age" : 25, "name" : "Josh", "status" : null, "hobbies" : ["football", "cooking"]} {"id" : 2, "age" : 19, "name" : "Alan", "status" : "married", "hobbies" : ["tennis", "art"]} $$) ``` ```response theme={null} ┌─name────┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ id │ Int64 │ │ │ │ │ │ │ age │ Int64 │ │ │ │ │ │ │ name │ String │ │ │ │ │ │ │ status │ Nullable(String) │ │ │ │ │ │ │ hobbies │ Array(String) │ │ │ │ │ │ └─────────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} SET schema_inference_make_columns_nullable = 0; DESC format(JSONEachRow, $$ {"id" : 1, "age" : 25, "name" : "Josh", "status" : null, "hobbies" : ["football", "cooking"]} {"id" : 2, "age" : 19, "name" : "Alan", "status" : "married", "hobbies" : ["tennis", "art"]} $$) ``` ```response theme={null} ┌─name────┬─type──────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ id │ Int64 │ │ │ │ │ │ │ age │ Int64 │ │ │ │ │ │ │ name │ String │ │ │ │ │ │ │ status │ String │ │ │ │ │ │ │ hobbies │ Array(String) │ │ │ │ │ │ └─────────┴───────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
#### input\_format\_try\_infer\_integers
此设置不适用于 `JSON` 数据类型。 启用后，ClickHouse 会在文本格式的 schema 推断 中尽量将数值推断为整数而不是浮点数。 如果样本数据中该列的所有数字都是整数，则结果类型为 `Int64`；如果至少有一个数字是浮点数，则结果类型为 `Float64`。 如果样本数据只包含整数，且至少有一个正整数超出 `Int64` 的表示范围，ClickHouse 将推断为 `UInt64`。 默认启用。 **示例** ```sql theme={null} SET input_format_try_infer_integers = 0 DESC format(JSONEachRow, $$ {"number" : 1} {"number" : 2} $$) ``` ```response theme={null} ┌─name───┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ number │ Nullable(Float64) │ │ │ │ │ │ └────────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} SET input_format_try_infer_integers = 1 DESC format(JSONEachRow, $$ {"number" : 1} {"number" : 2} $$) ``` ```response theme={null} ┌─name───┬─type────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ number │ Nullable(Int64) │ │ │ │ │ │ └────────┴─────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} DESC format(JSONEachRow, $$ {"number" : 1} {"number" : 18446744073709551615} $$) ``` ```response theme={null} ┌─name───┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ number │ Nullable(UInt64) │ │ │ │ │ │ └────────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} DESC format(JSONEachRow, $$ {"number" : 1} {"number" : 2.2} $$) ``` ```response theme={null} ┌─name───┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ number │ Nullable(Float64) │ │ │ │ │ │ └────────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
#### input\_format\_try\_infer\_datetimes
如果启用，ClickHouse 会在文本格式的 schema 推断中，尝试从字符串字段推断出 `DateTime` 或 `DateTime64` 类型。 如果样本数据中某一列的所有字段都成功解析为日期时间，结果类型将为 `DateTime` 或 `DateTime64(9)` (如果存在带小数部分的日期时间) ； 如果至少有一个字段未能解析为日期时间，结果类型将为 `String`。 默认启用。 **示例** ```sql theme={null} SET input_format_try_infer_datetimes = 0; DESC format(JSONEachRow, $$ {"datetime" : "2021-01-01 00:00:00", "datetime64" : "2021-01-01 00:00:00.000"} {"datetime" : "2022-01-01 00:00:00", "datetime64" : "2022-01-01 00:00:00.000"} $$) ``` ```response theme={null} ┌─name───────┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ datetime │ Nullable(String) │ │ │ │ │ │ │ datetime64 │ Nullable(String) │ │ │ │ │ │ └────────────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} SET input_format_try_infer_datetimes = 1; DESC format(JSONEachRow, $$ {"datetime" : "2021-01-01 00:00:00", "datetime64" : "2021-01-01 00:00:00.000"} {"datetime" : "2022-01-01 00:00:00", "datetime64" : "2022-01-01 00:00:00.000"} $$) ``` ```response theme={null} ┌─name───────┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ datetime │ Nullable(DateTime) │ │ │ │ │ │ │ datetime64 │ Nullable(DateTime64(9)) │ │ │ │ │ │ └────────────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} DESC format(JSONEachRow, $$ {"datetime" : "2021-01-01 00:00:00", "datetime64" : "2021-01-01 00:00:00.000"} {"datetime" : "unknown", "datetime64" : "unknown"} $$) ``` ```response theme={null} ┌─name───────┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ datetime │ Nullable(String) │ │ │ │ │ │ │ datetime64 │ Nullable(String) │ │ │ │ │ │ └────────────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
#### input\_format\_try\_infer\_datetimes\_only\_datetime64
如果启用，即使日期时间值不包含小数部分，只要启用了 `input_format_try_infer_datetimes`，ClickHouse 也始终会推断为 `DateTime64(9)`。 默认处于禁用状态。 **示例** ```sql theme={null} SET input_format_try_infer_datetimes = 1; SET input_format_try_infer_datetimes_only_datetime64 = 1; DESC format(JSONEachRow, $$ {"datetime" : "2021-01-01 00:00:00", "datetime64" : "2021-01-01 00:00:00.000"} {"datetime" : "2022-01-01 00:00:00", "datetime64" : "2022-01-01 00:00:00.000"} $$) ``` ```response theme={null} ┌─name───────┬─type────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ datetime │ Nullable(DateTime64(9)) │ │ │ │ │ │ │ datetime64 │ Nullable(DateTime64(9)) │ │ │ │ │ │ └────────────┴─────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` 注意：在 schema 推断期间解析日期时间时，会遵循 [date\_time\_input\_format](/zh/reference/settings/formats#date_time_input_format) 设置
#### input\_format\_try\_infer\_dates
如果启用，ClickHouse 会在文本格式的 schema 推断过程中，尝试从字符串字段中推断出 `Date` 类型。 如果样本数据中某一列的所有字段都成功解析为日期，则结果类型为 `Date`； 如果至少有一个字段未解析为日期，则结果类型为 `String`。 默认启用。 **示例** ```sql theme={null} SET input_format_try_infer_datetimes = 0, input_format_try_infer_dates = 0 DESC format(JSONEachRow, $$ {"date" : "2021-01-01"} {"date" : "2022-01-01"} $$) ``` ```response theme={null} ┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ date │ Nullable(String) │ │ │ │ │ │ └──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} SET input_format_try_infer_dates = 1 DESC format(JSONEachRow, $$ {"date" : "2021-01-01"} {"date" : "2022-01-01"} $$) ``` ```response theme={null} ┌─name─┬─type───────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ date │ Nullable(Date) │ │ │ │ │ │ └──────┴────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ``` ```sql theme={null} DESC format(JSONEachRow, $$ {"date" : "2021-01-01"} {"date" : "unknown"} $$) ``` ```response theme={null} ┌─name─┬─type─────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ date │ Nullable(String) │ │ │ │ │ │ └──────┴──────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
#### input\_format\_try\_infer\_exponent\_floats
如果启用，ClickHouse 将尝试在文本格式中推断以指数形式表示的浮点数 (JSON 除外，因为 JSON 中以指数形式表示的数值始终会被推断) 。 默认情况下处于禁用状态。 **示例** ```sql theme={null} SET input_format_try_infer_exponent_floats = 1; DESC format(CSV, $$1.1E10 2.3e-12 42E00 $$) ``` ```response theme={null} ┌─name─┬─type──────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ c1 │ Nullable(Float64) │ │ │ │ │ │ └──────┴───────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
## 自描述格式
自描述格式会在数据本身中包含有关其结构的信息， 例如带有说明的某种头部信息、二进制类型树，或某种表。 为了从这类格式的文件中自动推断 schema，ClickHouse 会读取其中包含 类型信息的部分数据，并将其转换为 ClickHouse 表的 schema。
### 带有 -WithNamesAndTypes 后缀的格式
ClickHouse 支持一些带有 -WithNamesAndTypes 后缀的文本格式。该后缀表示，在实际数据之前，数据中会额外包含两行，分别存放列名和类型。 对此类格式进行 schema 推断时，ClickHouse 会读取前两行并提取列名和类型。 **示例** ```sql theme={null} DESC format(TSVWithNamesAndTypes, $$num str arr UInt8 String Array(UInt8) 42 Hello, World! [1,2,3] $$) ``` ```response theme={null} ┌─name─┬─type─────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ num │ UInt8 │ │ │ │ │ │ │ str │ String │ │ │ │ │ │ │ arr │ Array(UInt8) │ │ │ │ │ │ └──────┴──────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
### 带元数据的 JSON 格式
某些 JSON 输入格式 ([JSON](/zh/reference/formats/JSON/JSON)、[JSONCompact](/zh/reference/formats/JSON/JSONCompact)、[JSONColumnsWithMetadata](/zh/reference/formats/JSON/JSONColumnsWithMetadata)) 包含带有列名和类型的元数据。 对于这类格式的 schema 推断，ClickHouse 会读取这些元数据。 **示例** ```sql theme={null} DESC format(JSON, $$ { "meta": [ { "name": "num", "type": "UInt8" }, { "name": "str", "type": "String" }, { "name": "arr", "type": "Array(UInt8)" } ], "data": [ { "num": 42, "str": "Hello, World", "arr": [1,2,3] } ], "rows": 1, "statistics": { "elapsed": 0.005723915, "rows_read": 1, "bytes_read": 1 } } $$) ``` ```response theme={null} ┌─name─┬─type─────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ num │ UInt8 │ │ │ │ │ │ │ str │ String │ │ │ │ │ │ │ arr │ Array(UInt8) │ │ │ │ │ │ └──────┴──────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
### Avro
在 Avro 格式中，ClickHouse 会从数据中读取 schema，并根据以下类型对应关系将其转换为 ClickHouse schema： | Avro 数据类型 | ClickHouse 数据类型 | | ---------------------------------- | ------------------------------------------------------------------------ | | `boolean` | [Bool](/zh/reference/data-types/boolean) | | `int` | [Int32](/zh/reference/data-types/int-uint) | | `int (date)` \* | [Date32](/zh/reference/data-types/date32) | | `long` | [Int64](/zh/reference/data-types/int-uint) | | `float` | [Float32](/zh/reference/data-types/float) | | `double` | [Float64](/zh/reference/data-types/float) | | `bytes`, `string` | [String](/zh/reference/data-types/string) | | `fixed` | [FixedString(N)](/zh/reference/data-types/fixedstring) | | `enum` | [Enum](/zh/reference/data-types/enum) | | `array(T)` | [Array(T)](/zh/reference/data-types/array) | | `union(null, T)`, `union(T, null)` | [Nullable(T)](/zh/reference/data-types/date) | | `null` | [Nullable(Nothing)](/zh/reference/data-types/special-data-types/nothing) | | `string (uuid)` \* | [UUID](/zh/reference/data-types/uuid) | | `binary (decimal)` \* | [Decimal(P, S)](/zh/reference/data-types/decimal) | * [Avro 逻辑类型](https://avro.apache.org/docs/current/spec.html#Logical+Types) 不支持其他 Avro 类型。
### Parquet
在 Parquet 格式中，ClickHouse 会从数据中读取其 schema，并根据以下类型对应关系将其转换为 ClickHouse schema： | Parquet 数据类型 | ClickHouse 数据类型 | | ---------------------------- | ------------------------------------------------- | | `BOOL` | [Bool](/zh/reference/data-types/boolean) | | `UINT8` | [UInt8](/zh/reference/data-types/int-uint) | | `INT8` | [Int8](/zh/reference/data-types/int-uint) | | `UINT16` | [UInt16](/zh/reference/data-types/int-uint) | | `INT16` | [Int16](/zh/reference/data-types/int-uint) | | `UINT32` | [UInt32](/zh/reference/data-types/int-uint) | | `INT32` | [Int32](/zh/reference/data-types/int-uint) | | `UINT64` | [UInt64](/zh/reference/data-types/int-uint) | | `INT64` | [Int64](/zh/reference/data-types/int-uint) | | `FLOAT` | [Float32](/zh/reference/data-types/float) | | `DOUBLE` | [Float64](/zh/reference/data-types/float) | | `DATE` | [Date32](/zh/reference/data-types/date32) | | `TIME (ms)` | [DateTime](/zh/reference/data-types/datetime) | | `TIMESTAMP`, `TIME (us, ns)` | [DateTime64](/zh/reference/data-types/datetime64) | | `STRING`, `BINARY` | [String](/zh/reference/data-types/string) | | `DECIMAL` | [Decimal](/zh/reference/data-types/decimal) | | `LIST` | [Array](/zh/reference/data-types/array) | | `STRUCT` | [Tuple](/zh/reference/data-types/tuple) | | `MAP` | [Map](/zh/reference/data-types/map) | 不支持其他 Parquet 类型。
### Arrow
在 Arrow 格式中，ClickHouse 会从数据中读取 schema，并根据以下类型对应关系将其转换为 ClickHouse schema： | Arrow 数据类型 | ClickHouse 数据类型 | | ------------------------------- | ------------------------------------------------- | | `BOOL` | [Bool](/zh/reference/data-types/boolean) | | `UINT8` | [UInt8](/zh/reference/data-types/int-uint) | | `INT8` | [Int8](/zh/reference/data-types/int-uint) | | `UINT16` | [UInt16](/zh/reference/data-types/int-uint) | | `INT16` | [Int16](/zh/reference/data-types/int-uint) | | `UINT32` | [UInt32](/zh/reference/data-types/int-uint) | | `INT32` | [Int32](/zh/reference/data-types/int-uint) | | `UINT64` | [UInt64](/zh/reference/data-types/int-uint) | | `INT64` | [Int64](/zh/reference/data-types/int-uint) | | `FLOAT`, `HALF_FLOAT` | [Float32](/zh/reference/data-types/float) | | `DOUBLE` | [Float64](/zh/reference/data-types/float) | | `DATE32` | [Date32](/zh/reference/data-types/date32) | | `DATE64` | [DateTime](/zh/reference/data-types/datetime) | | `TIMESTAMP`, `TIME32`, `TIME64` | [DateTime64](/zh/reference/data-types/datetime64) | | `STRING`, `BINARY` | [String](/zh/reference/data-types/string) | | `DECIMAL128`, `DECIMAL256` | [Decimal](/zh/reference/data-types/decimal) | | `LIST` | [Array](/zh/reference/data-types/array) | | `STRUCT` | [Tuple](/zh/reference/data-types/tuple) | | `MAP` | [Map](/zh/reference/data-types/map) | 不支持其他 Arrow 类型。
### ORC
在 ORC 格式中，ClickHouse 会从数据中读取 schema，并按照以下类型映射将其转换为 ClickHouse schema： | ORC data type | ClickHouse data type | | ------------------------------------ | ------------------------------------------------- | | `Boolean` | [Bool](/zh/reference/data-types/boolean) | | `Tinyint` | [Int8](/zh/reference/data-types/int-uint) | | `Smallint` | [Int16](/zh/reference/data-types/int-uint) | | `Int` | [Int32](/zh/reference/data-types/int-uint) | | `Bigint` | [Int64](/zh/reference/data-types/int-uint) | | `Float` | [Float32](/zh/reference/data-types/float) | | `Double` | [Float64](/zh/reference/data-types/float) | | `Date` | [Date32](/zh/reference/data-types/date32) | | `Timestamp` | [DateTime64](/zh/reference/data-types/datetime64) | | `String`, `Char`, `Varchar`,`BINARY` | [String](/zh/reference/data-types/string) | | `Decimal` | [Decimal](/zh/reference/data-types/decimal) | | `List` | [Array](/zh/reference/data-types/array) | | `Struct` | [Tuple](/zh/reference/data-types/tuple) | | `Map` | [Map](/zh/reference/data-types/map) | 不支持其他 ORC 类型。
### Native
Native 格式用于 ClickHouse 内部，并在数据中包含 schema。 在 schema 推断 中，ClickHouse 会直接从数据中读取 schema，无需任何转换。
## 带外部 schema 的格式
这类格式需要在单独的文件中使用特定的 schema 语言来定义数据的 schema。 为了自动从这类格式的文件中推断 schema，ClickHouse 会从单独的文件中读取外部 schema，并将其转换为 ClickHouse 表的 schema。
### Protobuf
在 Protobuf 格式的 schema 推断中，ClickHouse 使用以下类型映射： | Protobuf 数据类型 | ClickHouse 数据类型 | | ----------------------------- | ------------------------------------------- | | `bool` | [UInt8](/zh/reference/data-types/int-uint) | | `float` | [Float32](/zh/reference/data-types/float) | | `double` | [Float64](/zh/reference/data-types/float) | | `int32`, `sint32`, `sfixed32` | [Int32](/zh/reference/data-types/int-uint) | | `int64`, `sint64`, `sfixed64` | [Int64](/zh/reference/data-types/int-uint) | | `uint32`, `fixed32` | [UInt32](/zh/reference/data-types/int-uint) | | `uint64`, `fixed64` | [UInt64](/zh/reference/data-types/int-uint) | | `string`, `bytes` | [String](/zh/reference/data-types/string) | | `enum` | [Enum](/zh/reference/data-types/enum) | | `repeated T` | [Array(T)](/zh/reference/data-types/array) | | `message`, `group` | [Tuple](/zh/reference/data-types/tuple) |
### CapnProto
在 CapnProto 格式的 schema 推断 中，ClickHouse 使用以下类型映射： | CapnProto 数据类型 | ClickHouse 数据类型 | | ---------------------------------- | ------------------------------------------------ | | `Bool` | [UInt8](/zh/reference/data-types/int-uint) | | `Int8` | [Int8](/zh/reference/data-types/int-uint) | | `UInt8` | [UInt8](/zh/reference/data-types/int-uint) | | `Int16` | [Int16](/zh/reference/data-types/int-uint) | | `UInt16` | [UInt16](/zh/reference/data-types/int-uint) | | `Int32` | [Int32](/zh/reference/data-types/int-uint) | | `UInt32` | [UInt32](/zh/reference/data-types/int-uint) | | `Int64` | [Int64](/zh/reference/data-types/int-uint) | | `UInt64` | [UInt64](/zh/reference/data-types/int-uint) | | `Float32` | [Float32](/zh/reference/data-types/float) | | `Float64` | [Float64](/zh/reference/data-types/float) | | `Text`, `Data` | [String](/zh/reference/data-types/string) | | `enum` | [Enum](/zh/reference/data-types/enum) | | `List` | [Array](/zh/reference/data-types/array) | | `struct` | [Tuple](/zh/reference/data-types/tuple) | | `union(T, Void)`, `union(Void, T)` | [Nullable(T)](/zh/reference/data-types/nullable) |
## 强类型二进制格式
在这类格式中，每个序列化值都包含其类型信息 (以及可能包含其名称信息) ，但不包含整个表的信息。 对此类格式进行 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 使用以下类型映射： | MessagePack 数据类型 (`INSERT`) | ClickHouse 数据类型 | | ------------------------------------------------------------------ | ----------------------------------------------- | | `int N`, `uint N`, `negative fixint`, `positive fixint` | [Int64](/zh/reference/data-types/int-uint) | | `bool` | [UInt8](/zh/reference/data-types/int-uint) | | `fixstr`, `str 8`, `str 16`, `str 32`, `bin 8`, `bin 16`, `bin 32` | [String](/zh/reference/data-types/string) | | `float 32` | [Float32](/zh/reference/data-types/float) | | `float 64` | [Float64](/zh/reference/data-types/float) | | `uint 16` | [Date](/zh/reference/data-types/date) | | `uint 32` | [DateTime](/zh/reference/data-types/datetime) | | `uint 64` | [DateTime64](/zh/reference/data-types/datetime) | | `fixarray`, `array 16`, `array 32` | [Array](/zh/reference/data-types/array) | | `fixmap`, `map 16`, `map 32` | [Map](/zh/reference/data-types/map) | 默认情况下，所有推断出的类型都包含在 `Nullable` 中，但可以通过设置 `schema_inference_make_columns_nullable` 进行更改。
### BSONEachRow
在 BSONEachRow 中，每一行数据都表示为一个 BSON 文档。在进行 schema 推断时，ClickHouse 会逐个读取 BSON 文档，并从数据中提取 值、名称和类型，然后按照以下类型映射将这些类型转换为 ClickHouse 类型： | BSON 类型 | ClickHouse 类型 | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `\x08` boolean | [Bool](/zh/reference/data-types/boolean) | | `\x10` int32 | [Int32](/zh/reference/data-types/int-uint) | | `\x12` int64 | [Int64](/zh/reference/data-types/int-uint) | | `\x01` double | [Float64](/zh/reference/data-types/float) | | `\x09` datetime | [DateTime64](/zh/reference/data-types/datetime64) | | `\x05` binary with`\x00` binary subtype, `\x02` string, `\x0E` symbol, `\x0D` JavaScript code | [String](/zh/reference/data-types/string) | | `\x07` ObjectId, | [FixedString(12)](/zh/reference/data-types/fixedstring) | | `\x05` binary with `\x04` uuid subtype, size = 16 | [UUID](/zh/reference/data-types/uuid) | | `\x04` array | [Array](/zh/reference/data-types/array)/[Tuple](/zh/reference/data-types/tuple) (如果嵌套类型不同) | | `\x03` document | [命名元组](/zh/reference/data-types/tuple)/[Map](/zh/reference/data-types/map) (键为 String) | 默认情况下，所有推断出的类型都会包裹在 `Nullable` 中，但可以通过设置 `schema_inference_make_columns_nullable` 进行更改。
## schema 固定的格式
这类格式中的数据始终采用相同的 schema。
### LineAsString
在这种格式下，ClickHouse 会将数据中的整行读入一个 `String` 数据类型的单列中。该格式推断出的类型始终为 `String`，列名为 `line`。 **示例** ```sql theme={null} DESC format(LineAsString, 'Hello\nworld!') ``` ```response theme={null} ┌─name─┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ line │ String │ │ │ │ │ │ └──────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
### JSONAsString
在这种格式中，ClickHouse 会将数据中的整个 JSON 对象读取到一个 `String` 数据类型的列中。该格式推断出的类型始终为 `String`，列名为 `json`。 **示例** ```sql theme={null} DESC format(JSONAsString, '{"x" : 42, "y" : "Hello, World!"}') ``` ```response theme={null} ┌─name─┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ json │ String │ │ │ │ │ │ └──────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
### JSONAsObject
在这种格式中，ClickHouse 会将数据中的整个 JSON 对象读入具有 `JSON` 数据类型的单个列中。此格式推断出的类型始终为 `JSON`，列名为 `json`。 **示例** ```sql theme={null} DESC format(JSONAsObject, '{"x" : 42, "y" : "Hello, World!"}'); ``` ```response theme={null} ┌─name─┬─type─┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐ │ json │ JSON │ │ │ │ │ │ └──────┴──────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘ ```
## schema 推断模式
对一组数据文件进行 schema 推断时，可以使用 2 种不同的模式：`default` 和 `union`。 该模式由设置 `schema_inference_mode` 控制。
### 默认模式
在默认模式下，ClickHouse 假设所有文件都具有相同的 schema，并尝试逐个读取文件来推断 schema，直到成功为止。 示例： 假设我们有 3 个文件 `data1.jsonl`、`data2.jsonl` 和 `data3.jsonl`，内容如下： `data1.jsonl`: ```json theme={null} {"field1" : 1, "field2" : null} {"field1" : 2, "field2" : null} {"field1" : 3, "field2" : null} ``` `data2.jsonl`： ```json theme={null} {"field1" : 4, "field2" : "Data4"} {"field1" : 5, "field2" : "Data5"} {"field1" : 6, "field2" : "Data5"} ``` `data3.jsonl`: ```json theme={null} {"field1" : 7, "field2" : "Data7", "field3" : [1, 2, 3]} {"field1" : 8, "field2" : "Data8", "field3" : [4, 5, 6]} {"field1" : 9, "field2" : "Data9", "field3" : [7, 8, 9]} ``` 让我们尝试对这 3 个文件进行 schema 推断： ```sql title="Query" theme={null} :) DESCRIBE file('data{1,2,3}.jsonl') SETTINGS schema_inference_mode='default' ``` ```response title="Response" theme={null} ┌─name───┬─type─────────────┐ │ field1 │ Nullable(Int64) │ │ field2 │ Nullable(String) │ └────────┴──────────────────┘ ``` 正如我们所见，来自文件 `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`: ```json theme={null} {"field1" : 1} {"field1" : 2} {"field1" : 3} ``` `data2.jsonl`: ```json theme={null} {"field2" : "Data4"} {"field2" : "Data5"} {"field2" : "Data5"} ``` `data3.jsonl`： ```json theme={null} {"field3" : [1, 2, 3]} {"field3" : [4, 5, 6]} {"field3" : [7, 8, 9]} ``` 让我们尝试对这 3 个文件进行 schema 推断： ```sql title="Query" theme={null} :) DESCRIBE file('data{1,2,3}.jsonl') SETTINGS schema_inference_mode='union' ``` ```response title="Response" theme={null} ┌─name───┬─type───────────────────┐ │ field1 │ Nullable(Int64) │ │ field2 │ Nullable(String) │ │ field3 │ Array(Nullable(Int64)) │ └────────┴────────────────────────┘ ``` 可以看到，我们得到了所有文件中的全部字段。 注意： * 由于某些文件可能不包含结果 schema 中的某些列，union mode 仅支持能够读取部分列的格式 (如 JSONEachRow、Parquet、TSVWithNames 等) ，对于其他格式 (如 CSV、TSV、JSONCompactEachRow 等) 则不起作用。 * 如果 ClickHouse 无法从某个文件中推断出 schema，则会抛出异常。 * 如果文件很多，从所有文件中读取 schema 可能会耗费较长时间。
## 自动检测格式
如果未指定数据格式，且无法通过文件扩展名判断，ClickHouse 会尝试根据文件内容检测其格式。 **示例：** 假设我们有一个 `data` 文件，其内容如下： ```csv theme={null} "a","b" 1,"Data1" 2,"Data2" 3,"Data3" ``` 我们可以在不指定格式或结构的情况下查看并查询这个文件： ```sql theme={null} :) desc file(data); ``` ```repsonse theme={null} ┌─name─┬─type─────────────┐ │ a │ Nullable(Int64) │ │ b │ Nullable(String) │ └──────┴──────────────────┘ ``` ```sql theme={null} :) select * from file(data); ``` ```response theme={null} ┌─a─┬─b─────┐ │ 1 │ Data1 │ │ 2 │ Data2 │ │ 3 │ Data3 │ └───┴───────┘ ``` ClickHouse 只能识别部分格式，而且这种识别需要一定时间，因此最好始终明确指定格式。