Разработчик

Этот раздел будет сфокусирован на прикладных приложениях 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 можно было надёжно восстановить, мы сохраняем метаданные ключа pandas в FileMetaData со значением, сохранённым как:

{'index_columns': ['__index_level_0__', '__index_level_1__', ...],
 'column_indexes': [<ci0>, <ci1>, ..., <ciN>],
 'columns': [<c0>, <c1>, ...],
 'pandas_version': $VERSION}

Здесь, <c0>/<ci0> и так далее — словари, содержащие метаданные для каждого столбца, включая столбцы индекса. Это имеет JSON-формат:

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

# assuming there's at least 3 levels in the index
index_columns = metadata['index_columns']  # noqa: F821
columns = metadata['columns']  # noqa: F821
ith_index = 2
assert index_columns[ith_index] == '__index_level_2__'
ith_index_info = columns[-len(index_columns):][ith_index]
ith_index_level_name = ith_index_info['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 — физический тип хранения столбца, который является результатом str(dtype) для базового массива NumPy, содержащего данные. Таким образом, для 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}. Объекты могут быть сериализованы и сохранены в столбцах Parquet BYTE_ARRAY. Кодировка может быть одной из:

  • 'pickle'
  • 'msgpack'
  • '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': '0.20.0'}