HiveText

入力	出力	エイリアス
✔	✔

説明

HiveText は、Apache Hive のテーブルで使われるテキストシリアライゼーションフォーマット (Hive の LazySimpleSerDe が生成するフォーマット) を読み書きします。これは CSV に似た区切り付きテキストフォーマットで、フィールドは Hive のデフォルトのフィールド区切り文字 \x01 (Ctrl-A) で区切られます。フィールドのフィールド区切り文字は input_format_hive_text_fields_delimiter で設定できます。入力フォーマットとして使用する場合、データにはヘッダー行がありません。値は宛先テーブルのカラムに位置に基づいて対応付けられるため、カラム名と型はデータから推論されるのではなく、テーブル (または明示的に指定された構造) から取得されます。読み取り時、ClickHouse は日付と時刻を best-effort モードでパースし (date_time_input_format を参照) 、末尾の省略されたフィールドをカラムのデフォルト値で補完し、認識できないフィールドはスキップします。フィールド内では、値は Hive のネストされた区切り文字ではなく、CSV と同じエスケープ規則を使ってパースされます。特に、型 Array のカラムは角括弧付きの表現 (たとえば "['a','b','c']") から読み取られ、 Hive のコレクション区切り文字 \x02 で区切られた値からは読み取られません。

ネストされた区切り文字の設定は入力に影響しませんinput_format_hive_text_collection_items_delimiter および input_format_hive_text_map_keys_delimiter の設定は互換性のために受け付けられますが、現時点ではパース時に使用されません。ただし、出力側でネストされた値を書き込む際には使用されます。

デフォルトでは、行ごとにフィールド数が可変であることが許可されています ( input_format_hive_text_allow_variable_number_of_columns を参照) 。テーブルよりフィールド数が少ない行では、不足しているカラムがデフォルト値で補完され、余分な末尾フィールドがある行では、その余分なフィールドはスキップされます。

使用例

以下の例では、入力ファイルを読みやすくするため、input_format_hive_text_fields_delimiter を使ってデフォルトのフィールド区切り文字をコンマ (,) に上書きしています。

HiveTextファイルの読み込み

カンマ区切りのフィールドを含む hive_data.txt ファイルがあるとします。

hive_data.txt

1,3
3,5,9

カラム名と型を定義したテーブルを作成し、FORMAT HiveText を使ってそのテーブルにファイルの内容を挿入します:

Query

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

┌─a─┬─b─┬─c─┐
│ 1 │ 3 │ 0 │
│ 3 │ 5 │ 9 │
└───┴───┴───┘

最初の行 1,3 には 2 つのフィールドしかないため、不足しているカラム c にはデフォルト値 0 が設定されます。

可変数のカラム

デフォルトの input_format_hive_text_allow_variable_number_of_columns = 1 では、テーブルのカラム数より多くのフィールドを持つ行では、末尾の余分なフィールドはそのままスキップされます:

hive_extras.txt

1,2,3,4,5
6,7,8

Query

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

┌─a─┬─b─┬─c─┐
│ 1 │ 2 │ 3 │
│ 6 │ 7 │ 8 │
└───┴───┴───┘

代わりに input_format_hive_text_allow_variable_number_of_columns = 0 を設定すると、フィールド数が厳密にチェックされ、テーブルのフィールド数より少ない行があるとパース時に例外が発生します。

出力

出力フォーマットとして使用する場合、HiveText は各行を引用符で囲まずに書き込みます。最上位フィールドはフィールド区切り文字 (デフォルトは \x01) で区切られ、行は行区切り文字 (デフォルトは \n、format_hive_text_rows_delimiter で設定可能) で区切られます。ネスト型の値 (Array、Map、 Tuple) は括弧を付けずに書き込まれ、 Hive の LazySimpleSerDe と同様に、ネストレベルに応じた Hive の区切り文字で区切られます。最初の 3 つの区切り文字は、設定可能なフィールド区切り文字、input_format_hive_text_collection_items_delimiter (デフォルトは \x02。配列要素、マップエントリ、タプル要素に使用) 、および input_format_hive_text_map_keys_delimiter (デフォルトは \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 設定に依存しないため、その設定が unix_timestamp または iso であっても、出力は Hive で解析可能なままです。同じ理由で、Bool 値は常に true/false として書き込まれ、 bool_true_representation および bool_false_representation 設定には依存しません。また、NULL 値は常に Hive のデフォルトの null シーケンス \N として書き込まれ、format_csv_null_representation 設定には依存しません。これにより、これらの汎用テキスト設定にかかわらず、出力を Hive の LazySimpleSerDe で読み取れます。同様に、HiveText 入力フォーマットは常に \N を NULL として読み取り、これも format_csv_null_representation 設定には依存しないため、最上位スカラーの往復変換はこの設定に依存しません。有限ではない Float32 および Float64 の値は、ClickHouse で通常使用される nan/inf/-inf トークンではなく、Hive の Java 表記である NaN、Infinity、-Infinity を使用して書き込まれます。これにより、Hive の FLOAT/DOUBLE パーサーはこれらを NULL ではなく元の値として読み戻します。

Hive 互換の出力であり、入力フォーマットを介した完全な往復変換には対応していません出力側は Hive のデフォルトの LazySimpleSerDe を対象としており、 ClickHouse 独自の HiveText 入力とは対称ではありません。

ネストされた Array、Map および Tuple の値は、Hive のネストされた区切り文字を使用して (角括弧なしで) 書き込まれます。一方、入力フォーマットは各フィールドを CSV/角括弧付きの規則で解析し、 input_format_hive_text_collection_items_delimiter / input_format_hive_text_map_keys_delimiter を無視します。そのため、 SELECT [1, 2] FORMAT HiveText のようなネストされた出力は、 INSERT ... FORMAT HiveText では読み戻せません。往復変換できるのは最上位のスカラーフィールドのみで、かつデフォルトの \n 行区切り文字を使用する場合に限られます (次の項目を参照) 。
往復変換にはデフォルトの \n 行区切り文字も必要です。 format_hive_text_rows_delimiter を変更すると、出力では設定されたバイトで行が区切られますが、入力側は依然として改行ベースの 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 側では両者を区別できません。

Query

SELECT '20240305', tuple(123567, 'e01001', map('action1', 33333, 'act2', 5555)) FORMAT HiveText;

フォーマット設定

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`

SQLリファレンス

データ型

エンジン

関数

フォーマット

インターフェイス

設定

システムテーブル

データレイク

説明

使用例

HiveTextファイルの読み込み

可変数のカラム

出力

フォーマット設定

​説明

​使用例

​HiveTextファイルの読み込み

​可変数のカラム

​出力

​フォーマット設定

説明

使用例

HiveTextファイルの読み込み

可変数のカラム

出力

フォーマット設定