pandas.read_parquet#

pandas.read_parquet(path, engine='auto', columns=None, storage_options=None, dtype_backend=<no_default>, filesystem=None, filters=None, **kwargs)[源代码][源代码]#

从文件路径加载一个 parquet 对象，返回一个 DataFrame。

该函数自动处理从parquet文件读取数据，并创建具有适当结构的DataFrame。

参数:

路径str, 路径对象或类文件对象

字符串、路径对象（实现 os.PathLike[str]），或实现二进制 read() 函数的类文件对象。字符串可以是一个 URL。有效的 URL 方案包括 http、ftp、s3、gs 和 file。对于文件 URL，需要一个主机。一个本地文件可以是：file://localhost/path/to/table.parquet。文件 URL 也可以是包含多个分区 parquet 文件的目录路径。pyarrow 和 fastparquet 都支持目录路径以及文件 URL。一个目录路径可以是：file://localhost/path/to/tables 或 s3://bucket/partition_dir。

引擎{‘auto’, ‘pyarrow’, ‘fastparquet’}，默认 ‘auto’

要使用的 Parquet 库。如果是 ‘auto’，则使用选项 io.parquet.engine。默认的 io.parquet.engine 行为是尝试 ‘pyarrow’，如果 ‘pyarrow’ 不可用，则回退到 ‘fastparquet’。

使用 'pyarrow' 引擎且未提供存储选项，并且文件系统由 pyarrow.fs 和 fsspec 同时实现时（例如 “s3://”），则首先尝试使用 pyarrow.fs 文件系统。如果希望使用其 fsspec 实现，请使用已实例化的 fsspec 文件系统作为文件系统关键字。

列列表, 默认=无

如果不是 None，则只会从文件中读取这些列。

storage_optionsdict, 可选

对于特定的存储连接有意义的额外选项，例如主机、端口、用户名、密码等。对于HTTP(S) URL，键值对会作为头部选项转发给 urllib.request.Request。对于其他URL（例如以“s3://”和“gcs://”开头），键值对会转发给 fsspec.open。请参阅 fsspec 和 urllib 获取更多详情，关于存储选项的更多示例请参考这里。

Added in version 1.3.0.

dtype_backend{‘numpy_nullable’, ‘pyarrow’}

应用于结果 DataFrame 的后端数据类型（仍在实验中）。如果未指定，默认行为是不使用可空数据类型。如果指定，行为如下：

"numpy_nullable": 返回支持可空数据类型的 DataFrame
"pyarrow": 返回支持 pyarrow 的可空 ArrowDtype DataFrame

Added in version 2.0.

文件系统fsspec 或 pyarrow 文件系统，默认为 None

读取 parquet 文件时使用的文件系统对象。仅在 engine="pyarrow" 时实现。

Added in version 2.1.0.

过滤器List[Tuple] 或 List[List[Tuple]]，默认 None

要过滤数据。过滤语法：[[(列, 操作符, 值), …],…] 其中操作符为 [==, =, >, >=, <, <=, !=, in, not in] 最内层的元组通过 AND 操作转换为一组过滤器。外层的列表通过 OR 操作组合这些过滤器集。也可以使用单个元组列表，这意味着不在过滤器集之间进行 OR 操作。

使用此参数不会导致最终分区的行级过滤，除非还指定了 engine="pyarrow"。对于其他引擎，过滤仅在分区级别执行，即，防止加载某些行组和/或文件。

Added in version 2.1.0.

**kwargs

任何额外的 kwargs 都会传递给引擎。

返回:

DataFrame: 基于 parquet 文件的 DataFrame。

参见

DataFrame.to_parquet: 创建一个序列化 DataFrame 的 parquet 对象。

例子

>>> original_df = pd.DataFrame({"foo": range(5), "bar": range(5, 10)})
>>> original_df
   foo  bar
0    0    5
1    1    6
2    2    7
3    3    8
4    4    9
>>> df_parquet_bytes = original_df.to_parquet()
>>> from io import BytesIO
>>> restored_df = pd.read_parquet(BytesIO(df_parquet_bytes))
>>> restored_df
   foo  bar
0    0    5
1    1    6
2    2    7
3    3    8
4    4    9
>>> restored_df.equals(original_df)
True
>>> restored_bar = pd.read_parquet(BytesIO(df_parquet_bytes), columns=["bar"])
>>> restored_bar
    bar
0    5
1    6
2    7
3    8
4    9
>>> restored_bar.equals(original_df[["bar"]])
True

该函数使用直接传递给引擎的 kwargs。在以下示例中，我们使用 pyarrow 引擎的 filters 参数来过滤 DataFrame 的行。

由于 pyarrow 是默认引擎，我们可以省略 engine 参数。注意 filters 参数是由 pyarrow 引擎实现的，它可以受益于多线程，并且在内存使用方面也可能更经济。

>>> sel = [("foo", ">", 2)]
>>> restored_part = pd.read_parquet(BytesIO(df_parquet_bytes), filters=sel)
>>> restored_part
    foo  bar
0    3    8
1    4    9