开发者#

本节将重点介绍pandas的下游应用。

以 Apache Parquet 格式存储 pandas DataFrame 对象#

Apache Parquet格式提供文件和列级别的键值元数据，存储在 Parquet 文件的页脚中：

5: optional list<KeyValue> key_value_metadata

哪里KeyValue​

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

为了能够pandas.DataFrame忠实地重建 a，我们将 pandas元数据键存储在 a 中，FileMetaData并将值存储为：

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

<descr0>该字段中的“描述符”值'index_columns'是字符串（指列）或具有如下所述值的字典。

/等是包含每列元数据的字典，<c0>包括索引 columns。它具有 JSON 形式：<ci0>

{'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__'。

如果索引具有非 Nonename属性，并且没有其他列的名称与该值匹配，则该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 数组numpy_type的结果。str(dtype)因此，对于datetimetzisdatetime64[ns]和 categorical，它可以是任何受支持的整数分类类型。

该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: 。对象可以序列化并存储在Parquet 列中。编码可以是以下之一：{'encoding': encoding}BYTE_ARRAY

    • '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'
 }}