開発者#

このセクションでは、pandas のダウンストリームアプリケーションに焦点を当てます。

pandas DataFrame オブジェクトを Apache Parquet 形式で保存する#

Apache Parquet 形式は、ファイルとカラムレベルでキー値メタデータを提供し、Parquet ファイルのフッターに保存されます。

5: optional list<KeyValue> key_value_metadata

ここで KeyValue は

struct KeyValue {
  1: required string key
  2: optional string value
}

pandas.DataFrame を忠実に再構築できるように、FileMetaData に pandas メタデータキーを格納し、その値は次のように保存されます。

{'index_columns': [<descr0>, <descr1>, ...],
 'column_indexes': [<ci0>, <ci1>, ..., <ciN>],
 'columns': [<c0>, <c1>, ...],
 'pandas_version': $VERSION,
 'creator': {
   'library': $LIBRARY,
   'version': $LIBRARY_VERSION
 }}

'index_columns' フィールドの「記述子」値 <descr0> は文字列（カラムを参照）または以下の値を持つ辞書です。

<c0>/<ci0> などは、各カラムのメタデータ（*インデックスカラムを含む*）を含む辞書です。これは JSON 形式です。

{'name': column_name,
 'field_name': parquet_column_name,
 'pandas_type': pandas_type,
 'numpy_type': numpy_type,
 'metadata': metadata}

これらの詳細な仕様については、以下を参照してください。

インデックスメタデータ記述子#

RangeIndex は、シリアライズを必要とせず、メタデータとしてのみ保存できます。これらの記述子形式は次のとおりです。

index = pd.RangeIndex(0, 10, 2)
{
    "kind": "range",
    "name": index.name,
    "start": index.start,
    "stop": index.stop,
    "step": index.step,
}

他のインデックスタイプは、他の DataFrame カラムと一緒にデータカラムとしてシリアライズする必要があります。これらのメタデータは、データカラム内のフィールド名を示す文字列です。たとえば、'__index_level_0__' です。

インデックスに None 以外の name 属性があり、その値と一致する名前を持つ他のカラムがない場合、index.name の値を記述子として使用できます。それ以外の場合（名前のないインデックスや、他のカラム名と衝突する名前を持つインデックスの場合）、__index_level_\d+__ に一致するパターンを持つ曖昧さ解消名を使用する必要があります。データカラムとしての名前付きインデックスの場合、name 属性は常に上記のようにカラム記述子に保存されます。

カラムメタデータ#

pandas_type はカラムの論理型であり、次のいずれかです。

  • ブール型: 'bool'

  • 整数型: 'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', 'uint64'

  • 浮動小数点型: 'float16', 'float32', 'float64'

  • 日付と時刻の型: 'datetime', 'datetimetz', 'timedelta'

  • 文字列型: 'unicode', 'bytes'

  • カテゴリ型: 'categorical'

  • その他の Python オブジェクト: 'object'

numpy_type はカラムの物理ストレージタイプであり、データを保持する基になる NumPy 配列の str(dtype) の結果です。datetimetz の場合、これは datetime64[ns] であり、カテゴリ型の場合、サポートされている任意の整数カテゴリ型になります。

metadata フィールドは、次の場合を除いて None です。

  • datetimetz: {'timezone': zone, 'unit': 'ns'}、例: {'timezone', 'America/New_York', 'unit': 'ns'}。「unit」はオプションであり、省略された場合はナノ秒とみなされます。

  • categorical: {'num_categories': K, 'ordered': is_ordered, 'type': $TYPE}

    • ここで「type」はオプションであり、ここにネストされた pandas 型指定（ただしカテゴリ型ではない）を指定できます。

  • unicode: {'encoding': encoding}

    • エンコーディングはオプションであり、指定されていない場合は UTF-8 です。

  • object: {'encoding': encoding}。オブジェクトはシリアライズされ、BYTE_ARRAY Parquet カラムに保存できます。エンコーディングは次のいずれかです。

    • 'pickle'

    • 'bson'

    • 'json'

  • timedelta: {'unit': 'ns'}。「unit」はオプションであり、省略された場合はナノ秒とみなされます。このメタデータは全体的にオプションです。

これら以外の型では、'metadata' キーは省略できます。実装は、キーが存在しない場合に None を想定できます。

完全に形成されたメタデータの例として

{'index_columns': ['__index_level_0__'],
 'column_indexes': [
     {'name': None,
      'field_name': 'None',
      'pandas_type': 'unicode',
      'numpy_type': 'object',
      'metadata': {'encoding': 'UTF-8'}}
 ],
 'columns': [
     {'name': 'c0',
      'field_name': 'c0',
      'pandas_type': 'int8',
      'numpy_type': 'int8',
      'metadata': None},
     {'name': 'c1',
      'field_name': 'c1',
      'pandas_type': 'bytes',
      'numpy_type': 'object',
      'metadata': None},
     {'name': 'c2',
      'field_name': 'c2',
      'pandas_type': 'categorical',
      'numpy_type': 'int16',
      'metadata': {'num_categories': 1000, 'ordered': False}},
     {'name': 'c3',
      'field_name': 'c3',
      'pandas_type': 'datetimetz',
      'numpy_type': 'datetime64[ns]',
      'metadata': {'timezone': 'America/Los_Angeles'}},
     {'name': 'c4',
      'field_name': 'c4',
      'pandas_type': 'object',
      'numpy_type': 'object',
      'metadata': {'encoding': 'pickle'}},
     {'name': None,
      'field_name': '__index_level_0__',
      'pandas_type': 'int64',
      'numpy_type': 'int64',
      'metadata': None}
 ],
 'pandas_version': '1.4.0',
 'creator': {
   'library': 'pyarrow',
   'version': '0.13.0'
 }}