pyarrow.dataset.Scanner

class pyarrow.dataset.Scanner

基类：_Weakrefable

一种绑定了上下文和选项的物化扫描操作。

Scanner（扫描器）是用于将扫描任务、数据片段和数据源整合在一起的类。

__init__(*args, **kwargs)

方法

__init__(*args, **kwargs)
count_rows(self)	计算匹配扫描器过滤器（scanner filter）的行数。
from_batches(source, *, Schema schema=None)	从批次迭代器创建 Scanner。
from_dataset(Dataset dataset, *[, columns, ...])	从 Dataset 创建 Scanner，
from_fragment(Fragment fragment, *, ...[, ...])	从 Fragment 创建 Scanner，
head(self, int num_rows)	加载数据集的前 N 行。
scan_batches(self)	以记录批次（配合对应的片段）的形式消费 Scanner。
take(self, indices)	按索引选择数据行。
to_batches(self)	以记录批次的形式消费 Scanner。
to_reader(self)	将此 Scanner 作为 RecordBatchReader 消费。
to_table(self)	将 Scanner 转换为 Table。

属性

dataset_schema	从片段中读取批次时所使用的 Schema。
projected_schema	数据的物化 Schema，考虑了投影（projections）。

count_rows(self)

计算匹配扫描器过滤器（scanner filter）的行数。

返回：

countint

dataset_schema

从片段中读取批次时所使用的 Schema。

static from_batches(source, *, Schema schema=None, columns=None, Expression filter=None, int batch_size=_DEFAULT_BATCH_SIZE, int batch_readahead=_DEFAULT_BATCH_READAHEAD, int fragment_readahead=_DEFAULT_FRAGMENT_READAHEAD, FragmentScanOptions fragment_scan_options=None, bool use_threads=True, bool cache_metadata=True, MemoryPool memory_pool=None)

从批次迭代器创建 Scanner。

这会创建一个只能使用一次的 Scanner。它旨在支持从只能读取一次的数据源（例如 RecordBatchReader 或生成器）写入数据集（该过程需要一个 Scanner）。

参数:

source迭代器或兼容 Arrow 的 stream 对象

批次的迭代器。这可以是 pyarrow RecordBatchReader、任何实现了 Arrow PyCapsule 流协议的对象，或者是一个实际的 Python RecordBatch 迭代器。

schemaSchema

批次的 Schema（在传入 Python 迭代器时是必需的）。

columnslist[str] 或 dict[str, Expression], 默认 None

要投影的列。这可以是要包含的列名列表（顺序和重复项将保留），也可以是包含 {new_column_name: expression} 值的字典，用于更高级的投影。

列或表达式列表可以使用特殊字段 __batch_index（片段中批次的索引）、__fragment_index（数据集中片段的索引）、__last_in_fragment（批次是否是片段中的最后一个）和 __filename（源文件的名称或源片段的描述）。

列将被传递给数据集和相应的数据片段，以避免加载、复制和反序列化计算链下游不需要的列。默认情况下，所有可用列都会被投影。如果引用的任何列名不存在于数据集的模式中，则会引发异常。

filterExpression, default None

扫描将仅返回与过滤器匹配的行。如果可能，谓词将被下推以利用分区信息或在数据源中找到的内部元数据，例如 Parquet 统计信息。否则，它会在产生记录批次之前过滤已加载的记录批次。

batch_sizeint, default 131_072

扫描的记录批次的最大行数。如果扫描的记录批次溢出内存，则可以调用此方法来减小其大小。

batch_readaheadint, default 16

在一个文件中预读的批次数量。这可能不适用于所有文件格式。增加此数字会增加 RAM 使用量，但也可以提高 IO 利用率。

fragment_readaheadint, default 4

预读的文件数量。增加此数字会增加 RAM 使用量，但也可以提高 IO 利用率。

fragment_scan_optionsFragmentScanOptions, default None

特定于特定扫描和片段类型的选项，在同一数据集的不同扫描之间可能会有所不同。

use_threadsbool, 默认 True

如果启用，将使用由可用 CPU 核心数确定的最大并行度。

cache_metadatabool, default True

如果启用，扫描时可能会缓存元数据以加快重复扫描。

memory_poolMemoryPool, 默认 None

如果需要，用于内存分配。如果未指定，则使用默认池。

static from_dataset(Dataset dataset, *, columns=None, filter=None, int batch_size=_DEFAULT_BATCH_SIZE, int batch_readahead=_DEFAULT_BATCH_READAHEAD, int fragment_readahead=_DEFAULT_FRAGMENT_READAHEAD, FragmentScanOptions fragment_scan_options=None, bool use_threads=True, bool cache_metadata=True, MemoryPool memory_pool=None)

从 Dataset 创建 Scanner，

参数:

datasetDataset

要扫描的数据集。

columnslist[str] 或 dict[str, Expression], 默认 None

要投影的列。这可以是要包含的列名列表（顺序和重复项将保留），也可以是包含 {new_column_name: expression} 值的字典，用于更高级的投影。

列或表达式列表可以使用特殊字段 __batch_index（片段中批次的索引）、__fragment_index（数据集中片段的索引）、__last_in_fragment（批次是否是片段中的最后一个）和 __filename（源文件的名称或源片段的描述）。

列将被传递给数据集和相应的数据片段，以避免加载、复制和反序列化计算链下游不需要的列。默认情况下，所有可用列都会被投影。如果引用的任何列名不存在于数据集的模式中，则会引发异常。

filterExpression, default None

扫描将仅返回与过滤器匹配的行。如果可能，谓词将被下推以利用分区信息或在数据源中找到的内部元数据，例如 Parquet 统计信息。否则，它会在产生记录批次之前过滤已加载的记录批次。

batch_sizeint, default 131_072

扫描的记录批次的最大行数。如果扫描的记录批次溢出内存，则可以调用此方法来减小其大小。

batch_readaheadint, default 16

在一个文件中预读的批次数量。这可能不适用于所有文件格式。增加此数字会增加 RAM 使用量，但也可以提高 IO 利用率。

fragment_readaheadint, default 4

预读的文件数量。增加此数字会增加 RAM 使用量，但也可以提高 IO 利用率。

fragment_scan_optionsFragmentScanOptions, default None

特定于特定扫描和片段类型的选项，在同一数据集的不同扫描之间可能会有所不同。

use_threadsbool, 默认 True

如果启用，将使用由可用 CPU 核心数确定的最大并行度。

cache_metadatabool, default True

如果启用，扫描时可能会缓存元数据以加快重复扫描。

memory_poolMemoryPool, 默认 None

如果需要，用于内存分配。如果未指定，则使用默认池。

static from_fragment(Fragment fragment, *, Schema schema=None, columns=None, Expression filter=None, int batch_size=_DEFAULT_BATCH_SIZE, int batch_readahead=_DEFAULT_BATCH_READAHEAD, int fragment_readahead=_DEFAULT_FRAGMENT_READAHEAD, FragmentScanOptions fragment_scan_options=None, bool use_threads=True, bool cache_metadata=True, MemoryPool memory_pool=None)

从 Fragment 创建 Scanner，

参数:

fragmentFragment

要扫描的片段。

schemaSchema，可选

该片段的 Schema。

columnslist[str] 或 dict[str, Expression], 默认 None

要投影的列。这可以是要包含的列名列表（顺序和重复项将保留），也可以是包含 {new_column_name: expression} 值的字典，用于更高级的投影。

列或表达式列表可以使用特殊字段 __batch_index（片段中批次的索引）、__fragment_index（数据集中片段的索引）、__last_in_fragment（批次是否是片段中的最后一个）和 __filename（源文件的名称或源片段的描述）。

列将被传递给数据集和相应的数据片段，以避免加载、复制和反序列化计算链下游不需要的列。默认情况下，所有可用列都会被投影。如果引用的任何列名不存在于数据集的模式中，则会引发异常。

filterExpression, default None

扫描将仅返回与过滤器匹配的行。如果可能，谓词将被下推以利用分区信息或在数据源中找到的内部元数据，例如 Parquet 统计信息。否则，它会在产生记录批次之前过滤已加载的记录批次。

batch_sizeint, default 131_072

扫描的记录批次的最大行数。如果扫描的记录批次溢出内存，则可以调用此方法来减小其大小。

batch_readaheadint, default 16

在一个文件中预读的批次数量。这可能不适用于所有文件格式。增加此数字会增加 RAM 使用量，但也可以提高 IO 利用率。

fragment_readaheadint, default 4

预读的文件数量。增加此数字会增加 RAM 使用量，但也可以提高 IO 利用率。

fragment_scan_optionsFragmentScanOptions, default None

特定于特定扫描和片段类型的选项，在同一数据集的不同扫描之间可能会有所不同。

use_threadsbool, 默认 True

如果启用，将使用由可用 CPU 核心数确定的最大并行度。

cache_metadatabool, default True

如果启用，扫描时可能会缓存元数据以加快重复扫描。

memory_poolMemoryPool, 默认 None

如果需要，用于内存分配。如果未指定，则使用默认池。

head(self, int num_rows)

加载数据集的前 N 行。

参数:

num_rowsint

要加载的行数。

返回：

表

projected_schema

数据的物化 Schema，考虑了投影（projections）。

这是从扫描器返回的任何数据的 Schema。

scan_batches(self)

以记录批次（配合对应的片段）的形式消费 Scanner。

返回：

record_batchesTaggedRecordBatch 的迭代器

take(self, indices)

按索引选择数据行。

仅消费底层数据集中所需的批次。除此之外，它等同于 to_table().take(indices)。

参数:

indicesArray 或 array-like

要在数据集中选择的行索引。

返回：

表

to_batches(self)

以记录批次的形式消费 Scanner。

返回：

record_batchesiterator of RecordBatch

to_reader(self)

将此 Scanner 作为 RecordBatchReader 消费。

返回：

RecordBatchReader

to_table(self)

将 Scanner 转换为 Table。

谨慎使用此便捷工具。它会在创建表之前在内存中串行具体化扫描结果。

返回：

表