Apache Parquet データ型のマッピング

MATLAB^® は、列方向のデータを table と timetable で表します。table または timetable の各変数に、それぞれ異なるデータ型と任意数の列を使用できます。table および timetable の変数の形状としては列ベクトルが最も一般的です。

Apache^® Parquet ファイル形式は、列方向の異種混合データに使用されます。MATLAB table や timetable と同様に、Parquet ファイルでは列ごとにデータ型が異なっていても構いません。MATLAB の Parquet 関数は、Apache Arrow 機能を使用して Parquet ファイルの読み取りと書き込みを行います。MATLAB は、元の Arrow テーブル スキーマをカスタム メタデータとして Parquet ファイルに保存します。Arrow は元のテーブル スキーマを使用して、特定のデータ型をラウンドトリップします。

類似点はありますが、MATLAB table および timetable で許可されるデータ型が、Parquet ファイルで許可されるデータ型に完全にマッピングされないことがあります。場合によっては、MATLAB がデータ内の情報 (欠損値など) を保持するためにはデータ型変換の実行が必要となります。この変換の結果、データの精度が失われることがあります。

一般に、MATLAB table および timetable を Parquet ファイルに変換すると、次のように動作します。

• 元の table に設定されていたテーブル プロパティは保存されない。

• table の行名または timetable の行時間は、新しいテーブル変数に変換してから書き込まれる。

• Parquet ファイルから変数名を読み取るときに、無効なテーブル変数名は有効なテーブル変数名に変換される。

Parquet ファイルは少数のプリミティブ (または "物理") データ型を使用します。"論理" 型は、その解釈方法を指定することにより、物理型を拡張します。ここに一覧されていない Parquet データ型は、Parquet ファイル (JSON、BSON、バイナリなど) の読み取りや書き込みではサポートされません。

次の表は、MATLAB table および timetable で表現可能なデータ型と、それらのデータ型が Apache Arrow および Parquet ファイルの対応する型にどのようにマッピングされるかをまとめています。

数値データ型

Apache Parquet から MATLAB への数値データ型の読み取り

Apache Parquet のデータ型		Apache Arrow のデータ型	MATLAB table または timetable の変数の型	メモ
論理型	物理型
なし	DOUBLE	double	double	Parquet のデータ型は、64 ビットの浮動小数点値です。 MATLAB は Parquet ファイル内の null 浮動小数点値をすべて NaN 値に変換します。
なし	FLOAT	float	single	Parquet のデータ型は、32 ビットの浮動小数点値です。 MATLAB は Parquet ファイル内の null 浮動小数点値をすべて NaN 値に変換します。
INT bitWidth=8 isSigned=true	INT32	int8	int8	配列に null 値が含まれている場合、配列は MATLAB double に変換され、null 値は NaN に設定されます。 64 ビット整数は、値が flintmax より大きい場合、double に変換されるときに切り捨てられます。 parquetread は null 値を含む列を double 配列に変換します。 parquetDatastore は null 値をセンチネル値 0 としてインポートします。 int96 値は読み取り時に int64 値に切り捨てられます。
INT bitWidth=8 isSigned=false	INT32	uint8	uint8
INT bitWidth=16 isSigned=true	INT32	int16	int16
INT bitWidth=16 isSigned=false	INT32	uint16	uint16
なし	INT32	int32	int32
INT bitWidth=32 isSigned=false	INT32	uint32	uint32
INT bitWidth=64 isSigned=true	INT64	int64	int64
INT bitWidth=64 isSigned=false	INT64	uint64	uint64
なし	BOOLEAN	boolean	logical	配列の BOOLEAN 型に null 値が含まれている場合、parquetread は配列を MATLAB double データ型に変換し、null 値を NaN で埋めます。 parquetread は null 値を NaN に設定します。 parquetDatastore は null 値をセンチネル値 false としてインポートします。

MATLAB から Apache Parquet への数値データ型の書き込み

MATLAB table または timetable の変数の型	Apache Arrow のデータ型	Apache Parquet のデータ型		メモ
		論理型	物理型
double	double	なし	DOUBLE	MATLAB は Parquet ファイルの NaN 値を null に変換します。 これらのワークフローは、複素数値やスパース配列をサポートしていません。
single	float	なし	FLOAT
int8	int8	INT bitWidth=8 isSigned=true	INT32	これらのワークフローは、複素数値をサポートしていません。
uint8	uint8	INT bitWidth=8 isSigned=false	INT32
int16	int16	INT bitWidth=16 isSigned=true	INT32
uint16	uint16	INT bitWidth=16 isSigned=false	INT32
int32	int32	なし	INT32
uint32	uint32	INT bitWidth=32 isSigned=false	INT32
int64	int64	INT bitWidth=64 isSigned=true	INT64
uint64	uint64	INT bitWidth=64 isSigned=false	INT64
logical	boolean	なし	BOOLEAN	このワークフローはスパース配列をサポートしていません。

バイナリ データ型

Apache Parquet から MATLAB へのバイナリ データ型の読み取り

Apache Parquet のデータ型		Apache Arrow のデータ型	MATLAB table または timetable の変数の型	メモ
論理型	物理型
String	BYTE_ARRAY	String	string	—
String	BYTE_ARRAY	Dictionary index_type=int32 value_type=string メタデータに基づく ordered。	categorical	Parquet ファイルに元の Arrow スキーマが含まれている場合にのみ、Arrow はデータをディクショナリとして読み取ります。
なし	FIXED_LEN_BYTE_ARRAY	FixedSizeBinary(byte_width)	uint8 値のセル	—
なし	BYTE_ARRAY	バイナリ	uint8 値のセル	—

MATLAB から Apache Parquet へのバイナリ データ型の書き込み

MATLAB table または timetable の変数の型	Apache Arrow のデータ型	Apache Parquet のデータ型		メモ
		論理型	物理型
string	LargeString	String	BYTE_ARRAY	MATLAB は、string 配列を Arrow の LargeString 配列に変換します。 他の Parquet リーダー (PyArrow など) は、MATLAB により書き込まれた Parquet ファイルに保存されている元の Arrow テーブル スキーマに基づいて、Parquet の String 列を LargeString 配列としてインポートする場合があります。 string(missing) 値は、Parquet ファイルに null 値として書き込まれます。
char	LargeString	String	BYTE_ARRAY
cellstr	LargeString	String	BYTE_ARRAY
categorical	Dictionary values=string indices は int8、int16、int32、または int64 に設定できます。 ordered=true/false は、MATLAB Ordinal プロパティに基づいて true または false になります。	String	BYTE_ARRAY	—

日付と時刻のデータ型

Apache Parquet から MATLAB への日付と時刻データ型の読み取り

Apache Parquet のデータ型		Apache Arrow のデータ型	MATLAB table または timetable の変数の型	メモ
論理型	物理型
DATE	INT32	date32	datetime	INT32 値は、Unix エポック (1970 年 1 月 1 日) からの日数を表します。 null 値は NaT としてインポートされます。
Timestamp isAdjustedToUTC は true または false に設定できます。 TimeUnit = は、milliseconds、microseconds、または nanoseconds に設定できます。	INT64	timestamp unit tz=None	datetime	Parquet ファイルにメタデータとして元の Arrow テーブル スキーマが含まれている場合は、次のようになります。 timestamp データが UTC に合わせて調整されている場合、タイムゾーンは元のスキーマによって決まります。 元のスキーマにタイムゾーンが存在せず、isAdjustedToUTC が true である場合、MATLAB はインポートされる datetime 配列の TimeZone プロパティを UTC に設定します。 null、Timestamp、および Date の値は、NaT としてインポートされます。
Time isAdjustedToUTC は true または false に設定できます。 unit=milliseconds	INT32	time32 [ms] unit=ms	duration	null time32 値は MATLAB に NaN sec として読み取られます。
Time isAdjustedToUTC=true/false unit= microseconds nanoseconds	INT64	time64 [us/ns] unit は microseconds または nanoseconds に設定できます。	duration	null time64 値は MATLAB に NaN sec として読み取られます。

MATLAB から Apache Parquet への日付と時刻データ型の書き込み

MATLAB table または timetable の変数の型	Apache Arrow のデータ型	Apache Parquet のデータ型		メモ
		論理型	物理型
datetime TimeZone は空以外の値です。	timestamp unit=microseconds tz は、入力 datetime の TimeZone プロパティの値に設定されます。	Timestamp TimeUnit=microseconds isAdjustedToUTC=true	INT64	この型は時点を表します。 MATLAB datetime の精度は 1 ミリ秒まで切り捨てられます。表示形式の設定は保存されません。 表される日付にタイム ゾーンは設定されません。 tz は TimeZone プロパティに基づいています。 TimeZone プロパティが '' の場合、isAdjustedToUTC は false に設定されます。
duration	time64 unit=microseconds	Time unit=microseconds isAdjustedToUTC=true	INT64	MATLAB datetime の精度は 1 ミリ秒まで切り捨てられます。表示形式の設定は保存されません。 NaN sec は null 値として Parquet ファイルに書き込まれます。

入れ子にされたデータ

入れ子にされた table と入れ子にされた timetable を Parquet ファイルに書き込むには、parquetwrite を使用します。入れ子にされた構造化 Parquet ファイル データをインポートするには、parquetread を使用します。

Apache Parquet から MATLAB への入れ子にされた型の読み取り

Apache Parquet のデータ型		Apache Arrow のデータ型	MATLAB table または timetable の変数の型	メモ
論理型	物理型
LIST	任意	LIST	cell	MATLAB の cell (cellstrs を除く) は Arrow の LargeList 配列に変換されます。 他の Parquet リーダー (PyArrow など) は、元の Arrow テーブル スキーマに基づいて、Parquet の LIST 列を配列 LargeList としてインポートする場合があります。
任意の長さのタプル構成をもつ LIST	任意	任意の長さのタプル構成をもつ LIST	入れ子にされた table	LIST の子が任意の長さのタプルである場合、LIST は struct 配列として解釈されます。 任意の長さのタプル構成の詳細については、Parquet Logical Type Definitions を参照してください。

MATLAB から Parquet への入れ子にされた型の書き込み

MATLAB table または timetable の変数の型	Apache Arrow のデータ型	Apache Parquet のデータ型		メモ
		論理型	物理型
cell	LargeList	LIST	任意	MATLAB の cell (cellstrs を除く) は Arrow の LargeList 配列に変換されます。 他の Parquet リーダー (PyArrow など) は、元の Arrow テーブル スキーマに基づいて、Parquet の LIST 列を LargeList 配列としてインポートする場合があります。
入れ子にされた table	Struct	NONE	任意	Arrow は、Struct 配列を Parquet グループ注釈列として書き込みます。 これらが存在する場合、MATLAB table RowNames は、エクスポートされる Arrow Struct にフィールドとして追加されます。
入れ子にされた timetable	Struct	NONE	任意	MATLAB table RowTimes は、エクスポートされる Arrow Struct 配列に追加されます。

参考

parquetread | parquetwrite | write