pyarrow.parquet.ParquetFile#

class pyarrow.parquet.ParquetFile(source, *, metadata=None, common_metadata=None, read_dictionary=None, binary_type=None, list_type=None, memory_map=False, buffer_size=0, pre_buffer=False, coerce_int96_timestamp_unit=None, decryption_properties=None, thrift_string_size_limit=None, thrift_container_size_limit=None, filesystem=None, page_checksum_verification=False, arrow_extensions_enabled=True)[source]#

基类： object

单个 Parquet 文件的读取器接口。

参数:

sourcestr, pathlib.Path, pyarrow.NativeFile, or file-like object: 可读源。对于包含 Parquet 文件的字节或类缓冲区文件，请使用 pyarrow.BufferReader。
metadataFileMetaData, default None: 使用现有的元数据对象，而不是从文件中读取。
common_metadataFileMetaData, default None: 如果主文件的元数据中没有找到 pandas 模式元数据，则在读取时将使用此元数据，目前没有其他用途。
read_dictionarylist: 要直接读取为 DictionaryArray 的列名列表。
binary_typepyarrow.DataType, 默认值 None: 如果给定，Parquet 二进制列将以此数据类型读取。如果在 Parquet 元数据中找到序列化的 Arrow schema，则此设置将被忽略。
list_typepyarrow.DataType 的 子类, 默认值 None: 如果给定，非 MAP 重复列将作为此数据类型（pyarrow.ListType 或 pyarrow.LargeListType）的实例读取。如果在 Parquet 元数据中找到序列化的 Arrow schema，则此设置将被忽略。
memory_mapbool, 默认值 False: 如果源是文件路径，使用内存映射读取文件，这在某些环境下可以提高性能。
buffer_sizeint, 默认值 0: 如果为正，则在反序列化单个列块时执行读取缓冲。否则，IO 调用将不进行缓冲。
pre_bufferbool, default False: 合并并并行发出文件读取以提高高延迟文件系统（例如 S3）的性能。如果为 True，Arrow 将使用后台 I/O 线程池。
coerce_int96_timestamp_unitstr, 默认值 None: 将以 INT96 格式存储的时间戳强制转换为特定分辨率（例如 'ms'）。设置为 None 等同于 'ns'，因此 INT96 时间戳将被推断为纳秒级时间戳。
decryption_propertiesFileDecryptionProperties, 默认值 None: Parquet 模块化加密的文件解密属性。
thrift_string_size_limitint, 默认值 None: 如果不是 None，则覆盖解码 Thrift 结构时分配的最大总字符串大小。默认限制应足以满足大多数 Parquet 文件的需求。
thrift_container_size_limitint, 默认值 None: 如果不是 None，则覆盖解码 Thrift 结构时分配的最大容器总大小。默认限制应足以满足大多数 Parquet 文件的需求。
filesystemFileSystem, 默认值 None: 如果未传递任何内容，将根据路径推断。路径将尝试在本地磁盘文件系统中查找，否则将解析为 URI 以确定文件系统。
page_checksum_verificationbool, 默认值 False: 如果为 True，则验证从文件中读取的每个页面的校验和。
arrow_extensions_enabledbool, 默认值 True: 如果为 True，则尽可能将 Parquet 逻辑类型读取为 Arrow 扩展类型（例如，将 JSON 读取为规范的 arrow.json 扩展类型，或将 UUID 读取为规范的 arrow.uuid 扩展类型）。

示例

生成一个示例 PyArrow 表并将其写入 Parquet 文件

>>> import pyarrow as pa
>>> table = pa.table({'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})

>>> import pyarrow.parquet as pq
>>> pq.write_table(table, 'example.parquet')

从 Parquet 文件创建 ParquetFile 对象

>>> parquet_file = pq.ParquetFile('example.parquet')

读取数据

>>> parquet_file.read()
pyarrow.Table
n_legs: int64
animal: string
----
n_legs: [[2,2,4,4,5,100]]
animal: [["Flamingo","Parrot","Dog","Horse","Brittle stars","Centipede"]]

创建一个 ParquetFile 对象，其中“animal”列为 DictionaryArray

>>> parquet_file = pq.ParquetFile('example.parquet',
...                               read_dictionary=["animal"])
>>> parquet_file.read()
pyarrow.Table
n_legs: int64
animal: dictionary<values=string, indices=int32, ordered=0>
----
n_legs: [[2,2,4,4,5,100]]
animal: [  -- dictionary:
["Flamingo","Parrot",...,"Brittle stars","Centipede"]  -- indices:
[0,1,2,3,4,5]]

__init__(source, *, metadata=None, common_metadata=None, read_dictionary=None, binary_type=None, list_type=None, memory_map=False, buffer_size=0, pre_buffer=False, coerce_int96_timestamp_unit=None, decryption_properties=None, thrift_string_size_limit=None, thrift_container_size_limit=None, filesystem=None, page_checksum_verification=False, arrow_extensions_enabled=True)[source]#

方法

`__init__`(source, *[, metadata, ...])
`close`([force])
`iter_batches`([batch_size, row_groups, ...])	从 Parquet 文件读取流式批次。
`read`([columns, use_threads, use_pandas_metadata])	从 Parquet 格式读取表。
`read_row_group`(i[, columns, use_threads, ...])	从 Parquet 文件读取单个行组。
`read_row_groups`(row_groups[, columns, ...])	从 Parquet 文件读取多个行组。
`scan_contents`([columns, batch_size])	读取给定列和批次大小的文件内容。

属性

`closed`
`metadata`	返回 Parquet 元数据。
`num_row_groups`	返回 Parquet 文件的行组数。
`模式`	返回 Parquet 模式，未转换为 Arrow 类型
`schema_arrow`	返回推断的 Arrow 模式，从整个 Parquet 文件的模式转换而来

close(force: bool = False)[source]#

property closed: bool#

iter_batches(batch_size=65536, row_groups=None, columns=None, use_threads=True, use_pandas_metadata=False)[source]#

从 Parquet 文件读取流式批次。

参数:

batch_sizeint, default 64K: 每批次产生的最大记录数。如果文件中没有足够的行，批次可能会更小。
row_groupslist: 仅从文件中读取这些行组。
columnslist: 如果不为 None，则仅从文件中读取这些列。列名可以是嵌套字段的前缀，例如“a”将选择“a.b”、“a.c”和“a.d.e”。
use_threadsbool, 默认 True: 执行多线程列读取。
use_pandas_metadatabool, 默认值 False: 如果为 True 且文件具有自定义 pandas schema 元数据，请确保索引列也已加载。

生成：

pyarrow.RecordBatch: 每个批次的内容作为记录批次

示例

生成一个示例 Parquet 文件

>>> import pyarrow as pa
>>> table = pa.table({'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_table(table, 'example.parquet')
>>> parquet_file = pq.ParquetFile('example.parquet')
>>> for i in parquet_file.iter_batches():
...     print("RecordBatch")
...     print(i.to_pandas())
...
RecordBatch
   n_legs         animal
0       2       Flamingo
1       2         Parrot
2       4            Dog
3       4          Horse
4       5  Brittle stars
5     100      Centipede

property metadata#: 返回 Parquet 元数据。

property num_row_groups#

返回 Parquet 文件的行组数。

示例

>>> import pyarrow as pa
>>> table = pa.table({'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_table(table, 'example.parquet')
>>> parquet_file = pq.ParquetFile('example.parquet')

>>> parquet_file.num_row_groups
1

read(columns=None, use_threads=True, use_pandas_metadata=False)[source]#

从 Parquet 格式读取表。

参数:

columnslist: 如果不为 None，则仅从文件中读取这些列。列名可以是嵌套字段的前缀，例如“a”将选择“a.b”、“a.c”和“a.d.e”。
use_threadsbool, 默认 True: 执行多线程列读取。
use_pandas_metadatabool, 默认值 False: 如果为 True 且文件具有自定义 pandas schema 元数据，请确保索引列也已加载。

返回：

pyarrow.table.Table: 文件内容作为表（列的集合）。

示例

生成一个示例 Parquet 文件

>>> import pyarrow as pa
>>> table = pa.table({'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_table(table, 'example.parquet')
>>> parquet_file = pq.ParquetFile('example.parquet')

读取表

>>> parquet_file.read(columns=["animal"])
pyarrow.Table
animal: string
----
animal: [["Flamingo","Parrot",...,"Brittle stars","Centipede"]]

read_row_group(i, columns=None, use_threads=True, use_pandas_metadata=False)[source]#

从 Parquet 文件读取单个行组。

参数:

iint: 我们要读取的单个行组的索引。
columnslist: 如果不为 None，则仅从行组中读取这些列。列名可以是嵌套字段的前缀，例如“a”将选择“a.b”、“a.c”和“a.d.e”。
use_threadsbool, 默认 True: 执行多线程列读取。
use_pandas_metadatabool, 默认值 False: 如果为 True 且文件具有自定义 pandas schema 元数据，请确保索引列也已加载。

返回：

pyarrow.table.Table: 行组的内容作为表（列的集合）

示例

>>> import pyarrow as pa
>>> table = pa.table({'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_table(table, 'example.parquet')
>>> parquet_file = pq.ParquetFile('example.parquet')

>>> parquet_file.read_row_group(0)
pyarrow.Table
n_legs: int64
animal: string
----
n_legs: [[2,2,4,4,5,100]]
animal: [["Flamingo","Parrot",...,"Brittle stars","Centipede"]]

read_row_groups(row_groups, columns=None, use_threads=True, use_pandas_metadata=False)[source]#

从 Parquet 文件读取多个行组。

参数:

row_groupslist: 仅从文件中读取这些行组。
columnslist: 如果不为 None，则仅从行组中读取这些列。列名可以是嵌套字段的前缀，例如“a”将选择“a.b”、“a.c”和“a.d.e”。
use_threadsbool, 默认 True: 执行多线程列读取。
use_pandas_metadatabool, 默认值 False: 如果为 True 且文件具有自定义 pandas schema 元数据，请确保索引列也已加载。

返回：

pyarrow.table.Table: 行组的内容作为表（列的集合）。

示例

>>> import pyarrow as pa
>>> table = pa.table({'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_table(table, 'example.parquet')
>>> parquet_file = pq.ParquetFile('example.parquet')

>>> parquet_file.read_row_groups([0,0])
pyarrow.Table
n_legs: int64
animal: string
----
n_legs: [[2,2,4,4,5,...,2,4,4,5,100]]
animal: [["Flamingo","Parrot","Dog",...,"Brittle stars","Centipede"]]

scan_contents(columns=None, batch_size=65536)[source]#

读取给定列和批次大小的文件内容。

参数:

columnslist of integers, default None: 选择要读取的列，如果为 None 则扫描所有列。
batch_sizeint, default 64K: 内部一次读取的行数。

返回：

num_rowsint: 文件中的行数

备注

此函数的主要目的是进行基准测试。扫描在单个线程上执行。

示例

>>> import pyarrow as pa
>>> table = pa.table({'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_table(table, 'example.parquet')
>>> parquet_file = pq.ParquetFile('example.parquet')

>>> parquet_file.scan_contents()
6

property schema#: 返回 Parquet 模式，未转换为 Arrow 类型

property schema_arrow#

返回推断的 Arrow 模式，从整个 Parquet 文件的模式转换而来

示例

生成一个示例 Parquet 文件

>>> import pyarrow as pa
>>> table = pa.table({'n_legs': [2, 2, 4, 4, 5, 100],
...                   'animal': ["Flamingo", "Parrot", "Dog", "Horse",
...                              "Brittle stars", "Centipede"]})
>>> import pyarrow.parquet as pq
>>> pq.write_table(table, 'example.parquet')
>>> parquet_file = pq.ParquetFile('example.parquet')

读取 Arrow 模式

>>> parquet_file.schema_arrow
n_legs: int64
animal: string