> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.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`](/ko/reference/formats/CSV/CSV)와 유사하며 필드는
Hive 기본 구분자인 `\x01`(Ctrl-A)로 구분됩니다. 필드 구분자는
[`input_format_hive_text_fields_delimiter`](#format-settings)로 구성할 수 있습니다.

`HiveText`는 입력 전용 포맷입니다. 데이터에는 헤더 행이 없으며 값은
대상 테이블의 컬럼에 위치에 따라 매핑되므로, 컬럼 이름과 타입은 데이터에서
추론하지 않고 테이블(또는 명시적으로 제공된
구조)에서 가져옵니다. 읽는 동안 ClickHouse는
날짜와 시간을 best-effort 모드로 파싱하고([`date_time_input_format`](/ko/reference/settings/formats#date_time_input_format) 참조),
생략된 후행 필드는 컬럼 기본값으로 채우며, 인식하지 못하는 필드는
건너뜁니다.

필드 내부의 값은 Hive의 중첩 구분자가 아니라 `CSV`와 동일한 이스케이프 규칙으로
파싱됩니다. 특히,
[`Array`](/ko/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`으로 대신 설정하면
필드 수가 엄격하게 적용되며, 테이블보다 필드 수가 적은
행은 파싱 예외를 발생시킵니다.

<div id="format-settings">
  ## 포맷 설정
</div>

| Setting                                                   | Description                                                                  | Default |
| --------------------------------------------------------- | ---------------------------------------------------------------------------- | ------- |
| `input_format_hive_text_fields_delimiter`                 | Hive Text File에서 필드 사이를 구분하는 구분자                                             | `\x01`  |
| `input_format_hive_text_collection_items_delimiter`       | Hive Text File에서 컬렉션(배열 또는 맵) 항목 사이를 구분하는 구분자입니다. 허용되지만 현재는 파싱 중에 사용되지 않습니다. | `\x02`  |
| `input_format_hive_text_map_keys_delimiter`               | Hive Text File에서 맵의 키/값 쌍 사이를 구분하는 구분자입니다. 허용되지만 현재는 파싱 중에 사용되지 않습니다.        | `\x03`  |
| `input_format_hive_text_allow_variable_number_of_columns` | Hive Text 입력에서 추가 컬럼은 무시하고(파일에 예상보다 많은 컬럼이 있는 경우), 누락된 필드는 기본값으로 처리합니다.      | `1`     |