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_allow_variable_number_of_columns を参照) 。 テーブルよりフィールド数が少ない行では、不足しているカラムがデフォルト値で補完され、 余分な末尾フィールドがある行では、その余分なフィールドはスキップされます。

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

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

1,3
3,5,9

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

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;

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

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

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

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

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;

┌─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 ではなく元の値として読み戻します。

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