Feather File Format¶
Feather is a portable file format for storing Arrow tables or data frames (from languages like Python or R) that utilizes the Arrow IPC format internally. Feather was created early in the Arrow project as a proof of concept for fast, language-agnostic data frame storage for Python (pandas) and R. There are two file format versions for Feather:
Version 2 (V2), the default version, which is exactly represented as the Arrow IPC file format on disk. V2 files support storing all Arrow data types as well as compression with LZ4 or ZSTD. V2 was first made available in Apache Arrow 0.17.0.
Version 1 (V1), a legacy version available starting in 2016, replaced by V2. V1 files are distinct from Arrow IPC files and lack many features, such as the ability to store all Arrow data types. V1 files also lack compression support. We intend to maintain read support for V1 for the foreseeable future.
pyarrow.feather module contains the read and write functions for the
write_feather() accepts either a
import pyarrow.feather as feather feather.write_feather(df, '/path/to/file')
read_feather() reads a Feather file as a
read_table() reads a Feather file
read_table() and the result is converted to
# Result is pandas.DataFrame read_df = feather.read_feather('/path/to/file') # Result is pyarrow.Table read_arrow = feather.read_table('/path/to/file')
These functions can read and write with file-paths or file-like objects. For example:
with open('/path/to/file', 'wb') as f: feather.write_feather(df, f) with open('/path/to/file', 'rb') as f: read_df = feather.read_feather(f)
A file input to
read_feather must support seeking.
As of Apache Arrow version 0.17.0, Feather V2 files (the default version) support two fast compression libraries, LZ4 (using the frame format) and ZSTD. LZ4 is used by default if it is available (which it should be if you obtained pyarrow through a normal package manager):
# Uses LZ4 by default feather.write_feather(df, file_path) # Use LZ4 explicitly feather.write_feather(df, file_path, compression='lz4') # Use ZSTD feather.write_feather(df, file_path, compression='zstd') # Do not compress feather.write_feather(df, file_path, compression='uncompressed')
Note that the default LZ4 compression generally yields much smaller files without sacrificing much read or write performance. In some instances, LZ4-compressed files may be faster to read and write than uncompressed due to reduced disk IO requirements.
Writing Version 1 (V1) Files¶
For compatibility with libraries without support for Version 2 files, you can
write the version 1 format by passing
intend to maintain read support for V1 for the foreseeable future.