> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.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`](/ja/reference/formats/CSV/CSV) に似た区切り付きテキスト
フォーマットで、フィールドは Hive のデフォルトのフィールド区切り文字 `\x01` (Ctrl-A) で
区切られます。フィールドのフィールド区切り文字は
[`input_format_hive_text_fields_delimiter`](#format-settings) で設定できます。

入力フォーマットとして使用する場合、データにはヘッダー行がありません。値は宛先テーブルのカラムに位置に基づいて
対応付けられるため、カラム名と型はデータから推論されるのではなく、テーブル (または明示的に指定された
構造) から取得されます。読み取り時、ClickHouse は
日付と時刻を best-effort モードでパースし ([`date_time_input_format`](/ja/reference/settings/formats/date-time#date_time_input_format) を参照) 、
末尾の省略されたフィールドをカラムのデフォルト値で補完し、認識できないフィールドは
スキップします。

フィールド内では、値は Hive のネストされた区切り文字ではなく、`CSV` と同じエスケープ規則を使って
パースされます。特に、
型 [`Array`](/ja/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` には 2 つのフィールドしかないため、不足しているカラム `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="output">
  ## 出力
</div>

出力フォーマットとして使用する場合、`HiveText` は各行を引用符で囲まずに書き込みます。
最上位フィールドはフィールド区切り文字 (デフォルトは `\x01`) で区切られ、
行は行区切り文字 (デフォルトは `\n`、[`format_hive_text_rows_delimiter`](#format-settings)
で設定可能) で区切られます。ネスト型の値
([`Array`](/ja/reference/data-types/array)、[`Map`](/ja/reference/data-types/map)、
[`Tuple`](/ja/reference/data-types/tuple)) は括弧を付けずに書き込まれ、
Hive の `LazySimpleSerDe` と同様に、ネストレベルに応じた Hive の区切り文字で
区切られます。最初の 3 つの区切り文字は、設定可能なフィールド
区切り文字、[`input_format_hive_text_collection_items_delimiter`](#format-settings)
(デフォルトは `\x02`。配列要素、マップエントリ、タプル要素に使用) 、
および [`input_format_hive_text_map_keys_delimiter`](#format-settings) (デフォルトは `\x03`。
マップキーとその値の間に使用) です。さらに深いレベルでは、連続する制御文字
(`\x04`、`\x05` など、最大 8 レベル) がデフォルトで使用されます。これらの 8 レベルを超える
区切り文字を必要とするほど深くネストされた型ツリーは、Hive の `LazySimpleSerDe` にも
対応する区切り文字がないため、`NOT_IMPLEMENTED` 例外で拒否されます。自然な
Hive テキスト表現を持たないデータ型は出力でサポートされず、
`NOT_IMPLEMENTED` 例外が発生します。これには `AggregateFunction`、`Dynamic`、
`Variant`、`LowCardinality`、`Object`、および数値を基盤とする型である
`Enum`、`Time`、`Time64`、`Interval` が含まれます。後者に対応する型は Hive に
存在しないため、生の基盤数値として書き込むのではなく拒否されます。
幅の広い数値型 `Int128`、`UInt128`、`Int256`、`UInt256` も同じ理由で
拒否されます。Hive で最も幅の広い整数は `BIGINT` (64 ビット) であり、
最大精度が 38 の Hive `DECIMAL` でもこれらの値の範囲を格納できません。
同様に、精度が 38 を超える `Decimal` 値 (つまり `Decimal256`) は Hive
`DECIMAL` の最大精度を超えるため、拒否されます。同様に、`Map` のキーは
Primitive 型である必要があります。Hive ではマップを
`MAP<primitive_type, data_type>` として宣言するため、キー型が `Array`、
`Map`、または `Tuple` である `Map` (ClickHouse では許可されます) は、
そのような値を読み戻せる Hive スキーマが存在しないため、
`NOT_IMPLEMENTED` 例外で拒否されます。空のマップリテラル `map()` も同じ理由で
拒否されます。その型は `Map(Nothing, Nothing)` であり、`Nothing` は Hive の
`MAP<key_type, data_type>` 宣言で指定できる型ではありません。これらのチェックはすべて、
行が書き込まれる前に、宣言されたカラム型に対して事前に適用されます。型ツリー内のどこかに
サポートされない型が含まれるヘッダーを持つクエリは、実際の値がサポートされない
シリアライゼーションに到達しない場合でも拒否されます (たとえば、サポートされない型の
`Nullable` が `NULL` 値のみを保持する場合や、サポートされない要素型の空の `Array`/`Map`
など) 。これは、ファイルで宣言されたスキーマが依然としてどの Hive テーブルにも
属し得ないためです。

`Date`、`Date32`、`DateTime`、`DateTime64` は常にプレーンな
Hive の日付およびタイムスタンプテキスト (`yyyy-MM-dd` および `yyyy-MM-dd HH:mm:ss[.fffffffff]`) で書き込まれます。
これは [`date_time_output_format`](/ja/reference/settings/formats/date-time#date_time_output_format)
設定に依存しないため、その設定が
`unix_timestamp` または `iso` であっても、出力は Hive で解析可能なままです。

同じ理由で、`Bool` 値は常に `true`/`false` として書き込まれ、
[`bool_true_representation`](/ja/reference/settings/formats/bool#bool_true_representation)
および [`bool_false_representation`](/ja/reference/settings/formats/bool#bool_false_representation)
設定には依存しません。また、`NULL` 値は常に Hive のデフォルトの null シーケンス
`\N` として書き込まれ、[`format_csv_null_representation`](/ja/reference/settings/formats/format-csv#format_csv_null_representation)
設定には依存しません。これにより、これらの汎用テキスト設定にかかわらず、出力を Hive の `LazySimpleSerDe` で
読み取れます。同様に、`HiveText` 入力フォーマットは常に
`\N` を `NULL` として読み取り、これも
[`format_csv_null_representation`](/ja/reference/settings/formats/format-csv#format_csv_null_representation)
設定には依存しないため、最上位スカラーの往復変換はこの設定に依存しません。

有限ではない `Float32` および `Float64` の値は、ClickHouse で通常使用される `nan`/`inf`/`-inf`
トークンではなく、Hive の Java 表記である `NaN`、`Infinity`、`-Infinity` を使用して書き込まれます。
これにより、Hive の `FLOAT`/`DOUBLE` パーサーはこれらを `NULL` ではなく元の値として読み戻します。

<Info>
  **Hive 互換の出力であり、入力フォーマットを介した完全な往復変換には対応していません**

  出力側は Hive のデフォルトの `LazySimpleSerDe` を対象としており、
  ClickHouse 独自の `HiveText` 入力とは対称ではありません。

  * ネストされた [`Array`](/ja/reference/data-types/array)、[`Map`](/ja/reference/data-types/map)
    および [`Tuple`](/ja/reference/data-types/tuple) の値は、Hive のネストされた
    区切り文字を使用して (角括弧なしで) 書き込まれます。一方、入力フォーマットは各フィールドを
    `CSV`/角括弧付きの規則で解析し、
    [`input_format_hive_text_collection_items_delimiter`](#format-settings) /
    [`input_format_hive_text_map_keys_delimiter`](#format-settings) を無視します。そのため、
    `SELECT [1, 2] FORMAT HiveText` のようなネストされた出力は、
    `INSERT ... FORMAT HiveText` では読み戻せ**ません**。往復変換できるのは最上位の
    スカラーフィールドのみで、かつデフォルトの `\n` 行区切り文字を使用する場合に限られます
    (次の項目を参照) 。
  * 往復変換にはデフォルトの `\n` 行区切り文字も必要です。
    [`format_hive_text_rows_delimiter`](#format-settings) を変更すると、出力では設定された
    バイトで行が区切られますが、入力側は依然として改行ベースの
    `CSVRowInputFormat` であり、対応する `input_format_hive_text_rows_delimiter` はありません。
    したがって、複数行のスカラー出力である
    `SELECT number FROM numbers(3) FORMAT HiveText SETTINGS format_hive_text_rows_delimiter=';'`
    (`0;1;2;` を生成) は、`INSERT ... FORMAT HiveText` で 3 行として読み戻せ**ません**。
  * デフォルトの、エスケープなしの `LazySimpleSerDe` のサブセットのみが実装されています。フィールドは
    エスケープせずに書き込まれます (Hive のオプションの `ROW FORMAT DELIMITED ...
    ESCAPED BY` に相当するものはありません) 。また、`NULL` は常に `\N` として書き込まれます
    (`NULL DEFINED AS` に相当するものはありません) 。そのため、有効なフィールド、行、またはネストされた
    区切り文字を含む `String` はそのまま書き込まれ、読み戻す際に誤って解釈されます。これは、エスケープを
    行わない serde における Hive 自体の動作と一致します。同じ理由により、値が文字どおり `\N` である
    `String` (たとえば `SELECT '\\N'::String FORMAT HiveText`) は、実際の `NULL` と同じ
    2 バイトとして書き込まれるため、Hive 側では両者を区別できません。
</Info>

```sql title="Query" theme={null}
SELECT '20240305', tuple(123567, 'e01001', map('action1', 33333, 'act2', 5555)) FORMAT HiveText;
```

<div id="format-settings">
  ## フォーマット設定
</div>

| Setting                                                   | Description                                                                                 | Default |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------- |
| `input_format_hive_text_fields_delimiter`                 | Hive テキストファイル内のフィールド間の区切り文字                                                                 | `\x01`  |
| `input_format_hive_text_collection_items_delimiter`       | Hive テキストファイル内のコレクション (Array または マップ) の項目間の区切り文字。出力フォーマットで使用されます。指定できますが、現時点ではパース時に使用されません。 | `\x02`  |
| `input_format_hive_text_map_keys_delimiter`               | Hive テキストファイル内の マップ のキーと値のペア間の区切り文字。出力フォーマットで使用されます。指定できますが、現時点ではパース時に使用されません。              | `\x03`  |
| `input_format_hive_text_allow_variable_number_of_columns` | Hive Text 入力で余分なカラムを無視し (ファイルのカラム数が想定より多い場合) 、不足しているフィールドはデフォルト値として扱います                     | `1`     |
| `format_hive_text_rows_delimiter`                         | Hive Text 出力の各行末の区切り文字                                                                      | `\n`    |