入力データからの自動スキーマ推論
ClickHouseは、ほとんどすべてのサポートされている Input formats において、入力データの構造を自動的に判断できます。この文書では、スキーマ推論が使用される場合、様々な入力フォーマットとの動作、およびそれを制御する設定について説明します。
使用法
スキーマ推論は、ClickHouseが特定のデータフォーマットでデータを読み取る必要があるが、その構造が不明な場合に使用されます。
テーブル関数 file, s3, url, hdfs, azureBlobStorage
これらのテーブル関数には、入力データの構造を指定するオプションの引数 structure があります。この引数が指定されていないか、auto に設定されている場合、構造はデータから推論されます。
例:
user_files ディレクトリ内に、JSONEachRowフォーマットの hobbies.jsonl というファイルがあり、以下のような内容であるとしましょう：
ClickHouseは、このデータの構造を指定せずに読み取ることができます：
注意: フォーマット JSONEachRow は、自動的に拡張子 .jsonl から判断されました。
自動的に決定された構造は、DESCRIBE クエリを使用して確認できます：
テーブルエンジン File, S3, URL, HDFS, azureBlobStorage
CREATE TABLE クエリでカラムのリストが指定されていない場合、テーブルの構造はデータから自動的に推論されます。
例:
ファイル hobbies.jsonl を使用しましょう。このファイルからのデータで、エンジン File でテーブルを作成できます：
clickhouse-local
clickhouse-local には、入力データの構造を指定するオプションのパラメータ -S/--structure があります。このパラメータが指定されていないか、auto に設定されている場合、構造はデータから推論されます。
例:
ファイル hobbies.jsonl を使用しましょう。このファイルからデータをクエリするには、clickhouse-local を使用します：
挿入テーブルからの構造の使用
テーブル関数 file/s3/url/hdfs がデータをテーブルに挿入するために使用されるとき、データから抽出するのではなく、挿入テーブルの構造を使用するオプションがあります。これは、スキーマ推論が時間を要するため、挿入性能を向上させることができます。また、テーブルに最適化されたスキーマがある場合、型間の変換が行われないため、役立ちます。
この動作を制御する特別な設定 use_structure_from_insertion_table_in_table_functions があります。これは3つの可能な値を持ちます：
- 0 - テーブル関数はデータから構造を抽出します。
- 1 - テーブル関数は挿入テーブルから構造を使用します。
- 2 - ClickHouseは、挿入テーブルから構造を使用できるか、スキーマ推論を使用するかを自動的に判断します。デフォルト値です。
例 1:
次の構造を持つテーブル hobbies1 を作成しましょう：
ファイル hobbies.jsonl からデータを挿入します：
この場合、ファイルのすべてのカラムが変更なしでテーブルに挿入されるため、ClickHouseはスキーマ推論の代わりに挿入テーブルから構造を使用します。
例 2:
次の構造を持つテーブル hobbies2 を作成しましょう：
ファイル hobbies.jsonl からデータを挿入します：
この場合、SELECT クエリのすべてのカラムがテーブルに存在するため、ClickHouseは挿入テーブルから構造を使用します。なお、これはJSONEachRow、TSKV、Parquetなど、列のサブセットを読み取ることをサポートする入力フォーマットにのみ機能します（例として、TSVフォーマットでは機能しません）。
例 3:
次の構造を持つテーブル hobbies3 を作成しましょう：
ファイル hobbies.jsonl からデータを挿入します：
この場合、SELECT クエリで id カラムが使用されますが、テーブルにはこのカラムがない（identifierという名前のカラムがある）ため、ClickHouseは挿入テーブルから構造を使用できず、スキーマ推論が使用されます。
例 4:
次の構造を持つテーブル hobbies4 を作成しましょう：
ファイル hobbies.jsonl からデータを挿入します：
この場合、SELECT クエリでカラム hobbies に対して何らかの操作が行われるため、ClickHouseは挿入テーブルから構造を使用できず、スキーマ推論が使用されます。
スキーマ推論キャッシュ
ほとんどの入力フォーマットでは、スキーマ推論はデータを読み取って構造を判断するためにいくつかのデータを読み取ります。このプロセスは時間がかかる可能性があります。ClickHouseが同じファイルからデータを再び読み取る際に同じスキーマを推論するのを防ぐために、推論されたスキーマはキャッシュされ、同じファイルに再度アクセスすると、ClickHouseはキャッシュからスキーマを使用します。
このキャッシュを制御する特別な設定があります：
schema_inference_cache_max_elements_for_{file/s3/hdfs/url/azure}- 対応するテーブル関数に対する最大キャッシュスキーマ数。デフォルト値は4096です。これらの設定はサーバー設定で設定する必要があります。schema_inference_use_cache_for_{file,s3,hdfs,url,azure}- スキーマ推論のためのキャッシュの使用をオン/オフにすることを許可します。これらの設定はクエリで使用できます。
ファイルのスキーマは、データの変更やフォーマット設定の変更によって変更できます。この理由により、スキーマ推論キャッシュは、ファイルソース、フォーマット名、使用されたフォーマット設定、およびファイルの最終修正時刻によってスキーマを識別します。
注意: url テーブル関数でアクセスされる一部のファイルは、最終修正時刻に関する情報を含まない可能性があります。この場合、特別な設定 schema_inference_cache_require_modification_time_for_url があります。この設定を無効にすると、そのようなファイルに対して最終修正時刻なしでキャッシュからスキーマを使用することができます。
また、キャッシュ内のすべての現在のスキーマを持つシステムテーブル schema_inference_cache があり、システムクエリ SYSTEM DROP SCHEMA CACHE [FOR File/S3/URL/HDFS] を使用して、すべてのソースまたは特定のソースのスキーマキャッシュをクリーンアップできます。
例:
s3のサンプルデータセット github-2022.ndjson.gz の構造を推論して、スキーマ推論キャッシュの動作を確認してみましょう：
ご覧の通り、2回目のクエリはほぼ瞬時に成功しました。
推論されたスキーマに影響を与える設定を変更してみましょう：
キャッシュからのスキーマは同じファイルに対して使用されませんでした。なぜなら、推論されたスキーマに影響を与える設定が変更されたからです。
system.schema_inference_cache テーブルの内容を確認してみましょう：
ご覧の通り、同じファイルに対して2つの異なるスキーマがあります。
システムクエリを使用して、スキーマキャッシュをクリアします：
テキストフォーマット
テキストフォーマットの場合、ClickHouseはデータを行ごとに読み取り、フォーマットに従ってカラムの値を抽出し、各値の型を決定するために再帰的なパーサーとヒューリスティックを使用します。スキーマ推論で読み取るデータの最大行数とバイト数は、設定 input_format_max_rows_to_read_for_schema_inference（デフォルトは25000）と input_format_max_bytes_to_read_for_schema_inference（デフォルトは32MB）によって制御されます。デフォルトでは、すべての推論された型は Nullable ですが、設定 schema_inference_make_columns_nullable を設定することでこれを変更できます（例については settings セクションを参照）。
JSONフォーマット
JSONフォーマットでは、ClickHouseは値をJSON仕様に従って解析し、その後最も適切なデータ型を見つけようとします。
どのように機能するか、どの型が推論できるか、およびJSONフォーマットで使用できる特定の設定を見てみましょう。
例
ここでおよび今後の例では、 format テーブル関数が使用されます。
整数、浮動小数点、真偽値、文字列：
日付、日付時刻：
配列：
配列に null が含まれている場合、ClickHouseは他の配列要素から型を使用します：
名前付きタプル：
input_format_json_try_infer_named_tuples_from_objects を有効にすると、スキーマ推論中にClickHouseはJSONオブジェクトから名前付きタプルを推論しようとします。結果として得られる名前付きタプルは、サンプルデータのすべての対応するJSONオブジェクトからの要素を含みます。
名前なしタプル：
JSONフォーマットでは、異なる型の要素を持つ配列を名前なしタプルとして扱います。
いくつかの値が null または空である場合、他の行の対応する値から型を使用します：
マップ：
JSONでは、同じ型の値を持つオブジェクトをマップ型として読み取ることができます。ただし、input_format_json_read_objects_as_strings と input_format_json_try_infer_named_tuples_from_objects を無効にしている場合のみ機能します。
JSONオブジェクト型（設定 allow_experimental_object_type が有効な場合）:
ネストされた複雑な型：
ClickHouseがすべてのキーの型を判断できない場合（データがすべてnullまたは空のオブジェクト/空の配列のみを含む場合）、設定 input_format_json_infer_incomplete_types_as_strings が有効な場合は型 String が使用され、それ以外は例外がスローされます：
JSON設定
input_format_json_try_infer_numbers_from_strings
この設定を有効にすると、文字列値から数値推論が可能になります。
デフォルトではこの設定は無効です。
例:
input_format_json_try_infer_named_tuples_from_objects
この設定を有効にすると、JSONオブジェクトから名前付きタプルを推論できるようになります。結果として得られる名前付きタプルは、サンプルデータのすべての対応するJSONオブジェクトからの要素を含むことになります。JSONデータがスパースでない場合に便利で、データのサンプルがすべてのオブジェクトキーを含んでいる場合に役立ちます。
この設定はデフォルトで有効です。
例
結果：
結果：
結果:
有効な設定の場合:
結果:
input_format_json_read_objects_as_strings
この設定を有効にすると、ネストされたJSONオブジェクトを文字列として読み取ることができます。この設定を使用すると、JSONオブジェクト型を使用せずにネストされたJSONオブジェクトを読み取ることができます。
この設定はデフォルトで有効です。
注: この設定を有効にしても、input_format_json_try_infer_named_tuples_from_objectsが無効でなければ効果はありません。
input_format_json_read_numbers_as_strings
この設定を有効にすると、数値を文字列として読み取ることができます。
この設定はデフォルトで有効です。
例
input_format_json_read_bools_as_numbers
この設定を有効にすると、Bool値を数値として読み取ることができます。
この設定はデフォルトで有効です。
例:
input_format_json_read_bools_as_strings
この設定を有効にすると、Bool値を文字列として読み取ることができます。
この設定はデフォルトで有効です。
例:
input_format_json_read_arrays_as_strings
この設定を有効にすると、JSON配列の値を文字列として読み取ることができます。
この設定はデフォルトで有効です。
例
input_format_json_infer_incomplete_types_as_strings
この設定を有効にすると、スキーマ推論中にデータサンプルにNull/{}/[]のみを含むJSONキーに対してString型を使用できます。JSON形式では、対応する設定がすべて有効な場合は、任意の値をStringとして読み取ることができ、スキーマ推論中のCannot determine type for column 'column_name' by first 25000 rows of data, most likely this column contains only Nulls or empty Arrays/Mapsというエラーを回避できます。この設定により、未知の型を持つキーに対してString型を使用できます。
例:
結果:
CSV
CSV形式では、ClickHouseは行から区切り文字に従って列の値を抽出します。ClickHouseは、数字や文字列以外のすべての型が二重引用符で囲まれていることを期待しています。値が二重引用符で囲まれている場合、ClickHouseは再帰パーサーを使用して引用符内のデータを解析し、その後、最も適切なデータ型を見つけようとします。値が二重引用符で囲まれていない場合、ClickHouseはそれを数値として解析し、値が数値でない場合、ClickHouseは文字列として扱います。
ClickHouseが複雑な型をパーサーやヒューリスティックを使用して特定しないようにしたい場合は、input_format_csv_use_best_effort_in_schema_inferenceの設定を無効にすれば、ClickHouseはすべての列を文字列として扱います。
input_format_csv_detect_headerの設定が有効な場合、ClickHouseはスキーマを推論する際に列名（おそらく型も）を検出しようとします。この設定はデフォルトで有効です。
例:
整数、浮動小数点、Bool、文字列:
引用符なしの文字列:
日付、日付時刻:
配列:
配列にnullが含まれている場合、ClickHouseは他の配列要素の型を使用します:
マップ:
ネストされた配列とマップ:
ClickHouseが引用符内で型を特定できない場合、すなわちデータがnullのみを含む場合、ClickHouseはそれをStringとして扱います:
input_format_csv_use_best_effort_in_schema_inferenceの設定を無効にした例:
ヘッダー自動検出の例（input_format_csv_detect_headerが有効な場合）:
名前のみ:
名前と型:
注: ヘッダーは、少なくとも1つの非String型の列が存在する場合にのみ検出されます。すべての列がString型の場合、ヘッダーは検出されません:
CSV設定
input_format_csv_try_infer_numbers_from_strings
この設定を有効にすると、文字列から数値を推測できるようになります。
この設定はデフォルトで無効です。
例:
TSV/TSKV
TSV/TSKV形式では、ClickHouseはタブ区切り文字に従って行から列の値を抽出し、その後、抽出された値を再帰パーサーを使用して解析し、最も適切な型を判断します。型を特定できない場合、ClickHouseはこの値をStringとして扱います。
ClickHouseが複雑な型をパーサーやヒューリスティックを使用して特定しないようにしたい場合は、input_format_tsv_use_best_effort_in_schema_inferenceの設定を無効にすれば、ClickHouseはすべての列を文字列として扱います。
input_format_tsv_detect_headerの設定が有効な場合、ClickHouseはスキーマを推論する際に列名（おそらく型も）を検出しようとします。この設定はデフォルトで有効です。
例:
整数、浮動小数点、Bool、文字列:
日付、日付時刻:
配列:
配列にnullが含まれている場合、ClickHouseは他の配列要素の型を使用します:
タプル:
マップ:
ネストされた配列、タプル、およびマップ:
ClickHouseが型を特定できない場合、すなわちデータがnullのみを含む場合、ClickHouseはそれをStringとして扱います:
input_format_tsv_use_best_effort_in_schema_inferenceの設定を無効にした例:
ヘッダー自動検出の例（input_format_tsv_detect_headerが有効な場合）:
名前のみ:
名前と型:
注: ヘッダーは、少なくとも1つの非String型の列が存在する場合にのみ検出されます。すべての列がString型の場合、ヘッダーは検出されません:
Values
Valuesフォーマットでは、ClickHouseは行からカラムの値を抽出し、その後リテラルが解析される方法に似た再帰的なパーサーを使用して解析します。
例:
整数、浮動小数点数、ブール値、文字列:
日付、日時:
配列:
配列にnullが含まれている場合、ClickHouseは他の配列要素から型を使用します:
タプル:
マップ:
ネストされた配列、タプル、マップ:
ClickHouseが型を判断できない場合、データがすべてnullから構成されている場合、例外がスローされます:
設定input_format_tsv_use_best_effort_in_schema_inferenceが無効化された例:
CustomSeparated
CustomSeparatedフォーマットでは、ClickHouseは最初に指定された区切り文字に従って行からすべてのカラム値を抽出し、その後、エスケープルールに従って各値のデータ型を推測しようとします。
設定input_format_custom_detect_headerが有効になっている場合、ClickHouseはスキーマを推測する際にカラム名（おそらく型）のヘッダーを検出しようとします。この設定はデフォルトで有効です。
例
ヘッダーの自動検出（input_format_custom_detect_headerが有効な場合）の例:
Template
Templateフォーマットでは、ClickHouseは最初に指定されたテンプレートに従って行からすべてのカラム値を抽出し、その後、エスケープルールに従って各値のデータ型を推測しようとします。
例
次の内容を持つファイルresultsetがあるとしましょう:
次の内容を持つファイルrow_formatがあるとしましょう:
これにより、次のクエリを実行できます:
Regexp
Templateと同様に、Regexpフォーマットでは、ClickHouseは最初に指定された正規表現に従って行からすべてのカラム値を抽出し、その後、指定されたエスケープルールに従って各値のデータ型を推測しようとします。
例
Settings for text formats
input_format_max_rows_to_read_for_schema_inference/input_format_max_bytes_to_read_for_schema_inference
これらの設定は、スキーマ推測のために読み取るデータの量を制御します。 より多くの行/バイトが読み取られるほど、スキーマ推測により多くの時間がかかりますが、型を正しく決定できる可能性が高くなります（特に、データに多くのnullが含まれている場合）。
デフォルト値:
25000はinput_format_max_rows_to_read_for_schema_inference用。33554432（32 Mb）はinput_format_max_bytes_to_read_for_schema_inference用。
column_names_for_schema_inference
明示的なカラム名を持たないフォーマットのスキーマ推測で使用するカラム名のリスト。指定された名前はデフォルトの c1,c2,c3,... の代わりに使用されます。フォーマット: column1,column2,column3,...。
例
schema_inference_hints
自動的に決定されたタイプの代わりにスキーマ推測で使用するカラム名とタイプのリスト。フォーマット: 'column_name1 column_type1, column_name2 column_type2, ...'。 この設定は、自動的に決定できなかったカラムの型を指定するか、スキーマを最適化するために使用できます。
例
schema_inference_make_columns_nullable
スキーマ推測の際に型を Nullable にするかどうかを制御します。
この設定が有効な場合、すべての推測された型は Nullable になります。無効の場合、推測された型は決して Nullable にならず、設定が auto の場合、推測された型は、サンプルの解析中にカラムに NULL が含まれている場合のみ Nullable になります。またはファイルメタデータがカラムのnull許可に関する情報を含む場合のみ適用されます。
デフォルトで有効。
例
input_format_try_infer_integers
この設定は、JSON データ型には適用されません。
有効な場合、ClickHouseはテキストフォーマットにおいてスキーマ推測の際に浮動小数点数の代わりに整数を推測しようとします。
サンプルデータのカラム内のすべての数値が整数であれば、結果の型は Int64 になります。少なくとも1つの数値が浮動小数点数である場合、結果の型は Float64 になります。
サンプルデータが整数のみを含み、少なくとも1つの整数が正で Int64 をオーバーフローする場合、ClickHouseは UInt64 を推測します。
デフォルトで有効。
例
input_format_try_infer_datetimes
有効な場合、ClickHouseはテキストフォーマットにおいて文字列フィールドから DateTime または DateTime64 の推測を行います。
サンプルデータのカラム内のすべてのフィールドが日時として正常に解析された場合、結果の型は DateTime か DateTime64(9) になります（もし fractional part を持つ日時があれば）。
もし少なくとも1つのフィールドが日時として解析されなかった場合、結果の型は String になります。
デフォルトで有効。
例
input_format_try_infer_datetimes_only_datetime64
有効な場合、ClickHouseは input_format_try_infer_datetimes が有効な場合に常に DateTime64(9) を推測します。たとえ日時の値がfractional partを含まない場合でも。
デフォルトで無効。
例
注意: スキーマ推測中の日時の解析は設定 date_time_input_format に従います。
input_format_try_infer_dates
有効な場合、ClickHouseはテキストフォーマットにおいて文字列フィールドから Date の推測を行います。
サンプルデータのカラム内のすべてのフィールドが日付として正常に解析された場合、結果の型は Date になります。
少なくとも1つのフィールドが日付として解析されなかった場合、結果の型は String になります。
デフォルトで有効。
例
input_format_try_infer_exponent_floats
有効な場合、ClickHouseはテキストフォーマットにおいて指数形式の浮動小数点数の推測を試みます（JSON では指数形式の数字は常に推測されます）。
デフォルトで無効。
例
Self describing formats
自己記述フォーマットは、データの構造に関する情報をデータ自体に含んでいます。これは、説明のあるヘッダー、バイナリタイプツリー、または何らかの種類のテーブルである可能性があります。 そのようなフォーマットのファイルからスキーマを自動的に推測するために、ClickHouseは型に関する情報を含むデータの一部を読み取り、それをClickHouseテーブルのスキーマに変換します。
Formats with -WithNamesAndTypes suffix
ClickHouseは、-WithNamesAndTypesというサフィックスを持ついくつかのテキストフォーマットをサポートしています。このサフィックスは、データに実際のデータの前にカラム名とタイプを含む2つの追加行が含まれていることを意味します。 このようなフォーマットのスキーマ推論では、ClickHouseは最初の2行を読み取り、カラム名とタイプを抽出します。
例
JSON formats with metadata
いくつかのJSON入力フォーマット（JSON、JSONCompact、JSONColumnsWithMetadata）には、カラム名とタイプを含むメタデータが含まれています。 このようなフォーマットのスキーマ推論では、ClickHouseはこのメタデータを読み取ります。
例
Avro
Avroフォーマットでは、ClickHouseはデータからスキーマを読み取り、次のタイプマッチを使用してClickHouseスキーマに変換します：
| Avroデータタイプ | ClickHouseデータタイプ |
|---|---|
boolean | Bool |
int | Int32 |
int (date) * | Date32 |
long | Int64 |
float | Float32 |
double | Float64 |
bytes, string | String |
fixed | FixedString(N) |
enum | Enum |
array(T) | Array(T) |
union(null, T), union(T, null) | Nullable(T) |
null | Nullable(Nothing) |
string (uuid) * | UUID |
binary (decimal) * | Decimal(P, S) |
他のAvroタイプはサポートされていません。
Parquet
Parquetフォーマットでは、ClickHouseはデータからスキーマを読み取り、次のタイプマッチを使用してClickHouseスキーマに変換します：
| Parquetデータタイプ | ClickHouseデータタイプ |
|---|---|
BOOL | Bool |
UINT8 | UInt8 |
INT8 | Int8 |
UINT16 | UInt16 |
INT16 | Int16 |
UINT32 | UInt32 |
INT32 | Int32 |
UINT64 | UInt64 |
INT64 | Int64 |
FLOAT | Float32 |
DOUBLE | Float64 |
DATE | Date32 |
TIME (ms) | DateTime |
TIMESTAMP, TIME (us, ns) | DateTime64 |
STRING, BINARY | String |
DECIMAL | Decimal |
LIST | Array |
STRUCT | Tuple |
MAP | Map |
他のParquetタイプはサポートされていません。デフォルトでは、すべての推論されたタイプは Nullable 内にありますが、設定 schema_inference_make_columns_nullable を使用して変更することができます。
Arrow
Arrowフォーマットでは、ClickHouseはデータからスキーマを読み取り、次のタイプマッチを使用してClickHouseスキーマに変換します：
| Arrowデータタイプ | ClickHouseデータタイプ |
|---|---|
BOOL | Bool |
UINT8 | UInt8 |
INT8 | Int8 |
UINT16 | UInt16 |
INT16 | Int16 |
UINT32 | UInt32 |
INT32 | Int32 |
UINT64 | UInt64 |
INT64 | Int64 |
FLOAT, HALF_FLOAT | Float32 |
DOUBLE | Float64 |
DATE32 | Date32 |
DATE64 | DateTime |
TIMESTAMP, TIME32, TIME64 | DateTime64 |
STRING, BINARY | String |
DECIMAL128, DECIMAL256 | Decimal |
LIST | Array |
STRUCT | Tuple |
MAP | Map |
他のArrowタイプはサポートされていません。デフォルトでは、すべての推論されたタイプは Nullable 内にありますが、設定 schema_inference_make_columns_nullable を使用して変更することができます。
ORC
ORCフォーマットでは、ClickHouseはデータからスキーマを読み取り、次のタイプマッチを使用してClickHouseスキーマに変換します：
| ORCデータタイプ | ClickHouseデータタイプ |
|---|---|
Boolean | Bool |
Tinyint | Int8 |
Smallint | Int16 |
Int | Int32 |
Bigint | Int64 |
Float | Float32 |
Double | Float64 |
Date | Date32 |
Timestamp | DateTime64 |
String, Char, Varchar,BINARY | String |
Decimal | Decimal |
List | Array |
Struct | Tuple |
Map | Map |
他のORCタイプはサポートされていません。デフォルトでは、すべての推論されたタイプは Nullable 内にありますが、設定 schema_inference_make_columns_nullable を使用して変更することができます。
Native
ネイティブフォーマットはClickHouse内で使用され、データ内にスキーマが含まれています。 スキーマ推論では、ClickHouseはデータからスキーマを読み取りますが、変換は行いません。
Formats with external schema
そのようなフォーマットでは、特定のスキーマ言語でデータを説明するスキーマが別のファイルに必要です。 そのようなフォーマットのファイルからスキーマを自動的に推論するために、ClickHouseは別のファイルから外部スキーマを読み取り、それをClickHouseテーブルスキーマに変換します。
Protobuf
Protobufフォーマットのスキーマ推論では、ClickHouseは次のタイプマッチを使用します：
| Protobufデータタイプ | ClickHouseデータタイプ |
|---|---|
bool | UInt8 |
float | Float32 |
double | Float64 |
int32, sint32, sfixed32 | Int32 |
int64, sint64, sfixed64 | Int64 |
uint32, fixed32 | UInt32 |
uint64, fixed64 | UInt64 |
string, bytes | String |
enum | Enum |
repeated T | Array(T) |
message, group | Tuple |
CapnProto
CapnProtoフォーマットのスキーマ推論では、ClickHouseは次のタイプマッチを使用します：
| CapnProtoデータタイプ | ClickHouseデータタイプ |
|---|---|
Bool | UInt8 |
Int8 | Int8 |
UInt8 | UInt8 |
Int16 | Int16 |
UInt16 | UInt16 |
Int32 | Int32 |
UInt32 | UInt32 |
Int64 | Int64 |
UInt64 | UInt64 |
Float32 | Float32 |
Float64 | Float64 |
Text, Data | String |
enum | Enum |
List | Array |
struct | Tuple |
union(T, Void), union(Void, T) | Nullable(T) |
Strong-typed binary formats
そのようなフォーマットでは、各シリアライズされた値がその型（おそらく名前についても）に関する情報を含みますが、全体のテーブルに関する情報はありません。
そのようなフォーマットのスキーマ推論では、ClickHouseはデータを行ごとに読み取り（最大で input_format_max_rows_to_read_for_schema_inference 行または input_format_max_bytes_to_read_for_schema_inference バイト）、各値の型（おそらく名前）をデータから抽出し、その後それらの型をClickHouseの型に変換します。
MsgPack
MsgPackフォーマットでは、行間に区切りがありません。このフォーマットに対してスキーマ推論を使用するには、input_format_msgpack_number_of_columns 設定を使用してテーブルのカラム数を指定する必要があります。ClickHouseは次のタイプマッチを使用します：
MessagePackデータタイプ (INSERT) | ClickHouseデータタイプ |
|---|---|
int N, uint N, negative fixint, positive fixint | Int64 |
bool | UInt8 |
fixstr, str 8, str 16, str 32, bin 8, bin 16, bin 32 | String |
float 32 | Float32 |
float 64 | Float64 |
uint 16 | Date |
uint 32 | DateTime |
uint 64 | DateTime64 |
fixarray, array 16, array 32 | Array |
fixmap, map 16, map 32 | Map |
デフォルトでは、すべての推論されたタイプは Nullable 内にありますが、設定 schema_inference_make_columns_nullable を使用して変更することができます。
BSONEachRow
BSONEachRowでは、データの各行がBSONドキュメントとして表示されます。スキーマ推論では、ClickHouseはBSONドキュメントを1つずつ読み取り、データから値、名前、および型を抽出し、その後これらの型を次のタイプマッチを使用してClickHouseの型に変換します：
| BSONタイプ | ClickHouseタイプ |
|---|---|
\x08 boolean | Bool |
\x10 int32 | Int32 |
\x12 int64 | Int64 |
\x01 double | Float64 |
\x09 datetime | DateTime64 |
\x05 binary with\x00 binary subtype, \x02 string, \x0E symbol, \x0D JavaScript code | String |
\x07 ObjectId, | FixedString(12) |
\x05 binary with \x04 uuid subtype, size = 16 | UUID |
\x04 array | Array/Tuple (if nested types are different) |
\x03 document | Named Tuple/Map (with String keys) |
デフォルトでは、すべての推論されたタイプは Nullable 内にありますが、設定 schema_inference_make_columns_nullable を使用して変更することができます。
Formats with constant schema
そのようなフォーマットのデータは常に同じスキーマを持ちます。
LineAsString
このフォーマットでは、ClickHouseはデータから行全体を String データタイプの単一カラムに読み込みます。このフォーマットの推論された型は常に String で、カラム名は line です。
例
JSONAsString
このフォーマットでは、ClickHouseはデータから全体のJSONオブジェクトを String データタイプの単一カラムに読み込みます。このフォーマットの推論された型は常に String で、カラム名は json です。
例
JSONAsObject
このフォーマットでは、ClickHouseはデータから全体のJSONオブジェクトを Object('json') データタイプの単一カラムに読み込みます。このフォーマットの推論された型は常に String で、カラム名は json です。
注：このフォーマットは、allow_experimental_object_type が有効な場合にのみ機能します。
例
Schema inference modes
データファイルのセットからのスキーマ推論は、default と union の2つの異なるモードで動作します。
モードは、設定 schema_inference_mode によって制御されます。
Default mode
デフォルトモードでは、ClickHouseはすべてのファイルが同じスキーマを持つと仮定し、成功するまでファイルを1つずつ読み取ることによってスキーマを推論しようとします。
例：
例えば、次の内容の3つのファイル data1.jsonl、data2.jsonl、data3.jsonl があるとします：
data1.jsonl:
data2.jsonl:
data3.jsonl:
これらの3つのファイルに対してスキーマ推論を試みてみましょう：
結果：
見ての通り、ファイル data3.jsonl の field3 は存在していません。
これは、ClickHouseが最初に data1.jsonl からスキーマを推論しようとし、field2 にnullしかなかったため失敗し、次に data2.jsonl からスキーマを推論しようとして成功したため、data3.jsonlのデータが読み込まれなかったからです。
Union mode
ユニオンモードでは、ClickHouseはファイルが異なるスキーマを持つ可能性があると仮定し、すべてのファイルのスキーマを推論し、それらを共通のスキーマにユニオンします。
例えば、次の内容の3つのファイル data1.jsonl、data2.jsonl、data3.jsonl があるとしましょう：
data1.jsonl:
data2.jsonl:
data3.jsonl:
これらの3つのファイルに対してスキーマ推論を試みてみましょう：
結果：
見ての通り、すべてのファイルからの全フィールドが得られました。
注意：
- 一部のファイルは、結果スキーマからのいくつかのカラムを含まない可能性があるため、ユニオンモードは、JSONEachRow、Parquet、TSVWithNamesなどのカラムのサブセットを読み取ることをサポートするフォーマットにしか対応しておらず、CSV、TSV、JSONCompactEachRowなどの他のフォーマットでは機能しません。
- ClickHouseがファイルの1つからスキーマを推論できない場合、例外がスローされます。
- 多くのファイルがある場合、すべてのファイルからスキーマを読み取るのに時間がかかることがあります。
Automatic format detection
データフォーマットが指定されておらず、ファイル拡張子から決定できない場合、ClickHouseはその内容によってファイルフォーマットを検出しようとします。
例：
例えば、次の内容の data があります：
このファイルをフォーマットや構造を指定することなく調査し、クエリを実行することができます：
ClickHouseは一部のフォーマットのサブセットのみを検出でき、検出には時間がかかるため、常にフォーマットを明示的に指定することが望ましいです。
