> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> HiveText 格式文档

# HiveText

| 输入 | 输出 | 别名 |
| -- | -- | -- |
| ✔  | ✗  |    |

<div id="description">
  ## 说明
</div>

`HiveText` 用于读取 [Apache Hive](https://hive.apache.org/)
表使用的文本序列化格式 (即 Hive 的 `LazySimpleSerDe` 生成的格式) 。它是一种带分隔符的文本
格式，类似于 [`CSV`](/zh/reference/formats/CSV/CSV)，其中字段使用
Hive 默认的 `\x01` (Ctrl-A) 作为分隔符。字段分隔符
可通过 [`input_format_hive_text_fields_delimiter`](#format-settings) 配置。

`HiveText` 是一种仅用于输入的格式。数据没有表头：值会按位置映射到目标表的各列，因此列名和类型取自该表 (或显式提供的
结构) ，而不是从数据中自动推断。读取时，ClickHouse 会以尽力而为模式解析
日期和时间 (参见 [`date_time_input_format`](/zh/reference/settings/formats#date_time_input_format)) ，
用列默认值填充末尾省略的字段，并跳过无法
识别的字段。

在单个字段内，值会使用与 `CSV` 相同的转义规则进行解析，而不是使用
Hive 的嵌套分隔符。特别是，类型为
[`Array`](/zh/reference/data-types/array) 的列会从带方括号的
表示形式读取 (例如 `"['a','b','c']"`) ，而不是从由
Hive 集合分隔符 `\x02` 分隔的值中读取。

<Info>
  **嵌套分隔符设置不起作用**

  [`input_format_hive_text_collection_items_delimiter`](#format-settings) 和
  [`input_format_hive_text_map_keys_delimiter`](#format-settings) 设置
  会出于兼容性而被接受，但当前解析时并不会使用。
</Info>

默认情况下，允许行包含数量不固定的字段 (参见
[`input_format_hive_text_allow_variable_number_of_columns`](#format-settings)) ：
字段数少于表列数的行会用默认值填充缺失列，而包含额外尾随字段的行会跳过这些多余字段。

<div id="example-usage">
  ## 示例用法
</div>

下面的示例通过 [`input_format_hive_text_fields_delimiter`](#format-settings) 将默认字段分隔符改为逗号 (`,`) ，让输入
文件更易于阅读。

<div id="reading-data">
  ### 读取 HiveText 文件
</div>

假设有一个名为 `hive_data.txt` 的文件，其字段由逗号分隔：

```text title="hive_data.txt" theme={null}
1,3
3,5,9
```

我们创建一个表，定义列名和类型，然后使用 `FORMAT HiveText` 将文件插入该表：

```sql title="Query" theme={null}
CREATE TABLE test_tbl (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_tbl FROM INFILE 'hive_data.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_tbl;
```

```response title="Response" theme={null}
┌─a─┬─b─┬─c─┐
│ 1 │ 3 │ 0 │
│ 3 │ 5 │ 9 │
└───┴───┴───┘
```

请注意，第一行 `1,3` 只有两个字段，因此缺失的列 `c`
会以默认值 `0` 进行填充。

<div id="variable-number-of-columns">
  ### 可变列数
</div>

在默认设置 `input_format_hive_text_allow_variable_number_of_columns = 1` 下，
如果某些行的字段数多于表中的列数，末尾多出的字段会被直接跳过：

```text title="hive_extras.txt" theme={null}
1,2,3,4,5
6,7,8
```

```sql title="Query" theme={null}
CREATE TABLE test_extras (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_extras FROM INFILE 'hive_extras.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_extras ORDER BY a;
```

```response title="Response" theme={null}
┌─a─┬─b─┬─c─┐
│ 1 │ 2 │ 3 │
│ 6 │ 7 │ 8 │
└───┴───┴───┘
```

改为将 `input_format_hive_text_allow_variable_number_of_columns = 0` 设为 0
会强制要求字段数严格一致，而当某一行的字段数少于表中的字段数时，会引发
解析异常。

<div id="format-settings">
  ## 格式设置
</div>

| 设置                                                        | 说明                                                        | 默认值    |
| --------------------------------------------------------- | --------------------------------------------------------- | ------ |
| `input_format_hive_text_fields_delimiter`                 | Hive Text File 中字段之间的分隔符                                  | `\x01` |
| `input_format_hive_text_collection_items_delimiter`       | Hive Text File 中集合 (Array 或 map) 元素之间的分隔符。可接受，但当前在解析时未使用。 | `\x02` |
| `input_format_hive_text_map_keys_delimiter`               | Hive Text File 中一对 map 键/值之间的分隔符。可接受，但当前在解析时未使用。          | `\x03` |
| `input_format_hive_text_allow_variable_number_of_columns` | 忽略 Hive Text 输入中的多余列 (如果文件中的列数超过预期) ，并将缺失字段视为默认值          | `1`    |