pyarrow.dataset.Dataset

class pyarrow.dataset.Dataset

基类： _Weakrefable

数据片段及潜在子数据集的集合。

Arrow Datasets 允许您查询跨多个文件拆分的数据。数据的这种分片可能表示分区，这可以加速仅涉及部分分区（文件）的查询。

__init__(*args, **kwargs)

方法

__init__(*args, **kwargs)
count_rows(self, Expression filter=None, ...)	计算匹配扫描器过滤器（scanner filter）的行数。
filter(self, expression)	对数据集应用行过滤器。
get_fragments(self, Expression filter=None)	返回此数据集中片段的迭代器。
head(self, int num_rows[, columns])	加载数据集的前 N 行。
join(self, right_dataset, keys[, ...])	在此数据集和另一个数据集之间执行连接操作。
join_asof(self, right_dataset, on, by, tolerance)	在此数据集和另一个数据集之间执行 asof 连接操作。
replace_schema(self, Schema schema)	返回此数据集的副本，并使用不同的模式。
scanner(self[, columns, filter])	针对数据集构建扫描操作。
sort_by(self, sorting, **kwargs)	按一列或多列对数据集进行排序。
take(self, indices[, columns])	按索引选择数据行。
to_batches(self[, columns])	将数据集读取为具体化的记录批次（materialized record batches）。
to_table(self[, columns])	将数据集读取为 Arrow 表。

属性

partition_expression	对所有此数据集查看的数据评估为 true 的表达式。
模式	完整数据集的公共模式

count_rows(self, 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 filter）的行数。

参数:

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

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

返回：

countint

filter(self, expression)

对数据集应用行过滤器。

参数:

expressionExpression

应应用于数据集的过滤器。

返回：

数据集

get_fragments(self, Expression filter=None)

返回此数据集中片段的迭代器。

参数:

filterExpression, default None

返回匹配可选过滤器的片段，使用 partition_expression 或内部信息（如 Parquet 的统计信息）。

返回：

fragmentsiterator of Fragment

head(self, int num_rows, 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)

加载数据集的前 N 行。

参数:

num_rowsint

要加载的行数。

columnslist of str, default 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

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

返回：

tableTable

join(self, right_dataset, keys, right_keys=None, join_type='left outer', left_suffix=None, right_suffix=None, coalesce_keys=True, use_threads=True)

在此数据集和另一个数据集之间执行连接操作。

连接的结果将是一个新的数据集，可以对其应用进一步的操作。

参数:

right_datasetdataset

要连接到当前数据集的数据集，在连接操作中充当右侧数据集。

keysstr 或 list[str]

当前数据集中应用于连接操作左侧键的列。

right_keysstr 或 list[str], 默认 None

右侧数据集中应在连接操作中作为键使用的列。当为 None 时，使用与左侧数据集相同的键名。

join_typestr, 默认 “left outer”

应执行的 Join 类型，取值包括（“left semi”, “right semi”, “left anti”, “right anti”, “inner”, “left outer”, “right outer”, “full outer”）

left_suffixstr, 默认 None

要添加到右侧列名的后缀。这可以防止左右数据集中的列名冲突。

right_suffixstr, 默认 None

要添加到左侧列名的后缀。这可以防止左右数据集中的列名冲突。

coalesce_keysbool, 默认 True

是否应从 Join 结果的一侧省略重复的键。

use_threadsbool, 默认 True

是否使用多线程。

返回：

InMemoryDataset

join_asof(self, right_dataset, on, by, tolerance, right_on=None, right_by=None)

在此数据集和另一个数据集之间执行 asof 连接操作。

这类似于左连接，但我们匹配最接近的键而不是相等的键。两个数据集都必须按键排序。这种连接类型对于未完美对齐的时间序列数据最有用。

在用“on”搜索之前，可选地在“by”上匹配等效键。

连接的结果将是一个新的数据集，可以对其应用进一步的操作。

参数:

right_datasetdataset

要连接到当前数据集的数据集，在连接操作中充当右侧数据集。

onstr

当前数据集中应用于连接操作左侧“on”键的列。

在“on”键上使用不精确匹配，即当且仅当 right.on - left.on 在区间 [min(0, tolerance), max(0, tolerance)] 内时，该行被视为匹配。

输入表必须按“on”键排序。必须是单个字段的公共类型。

目前，“on”键必须是整数、日期或时间戳类型。

bystr 或 list[str]

当前数据集中应用于连接操作左侧键的列。连接操作仅对这些列中的匹配项执行。

toleranceint

不精确“on”键匹配的容差。当 right.on - left.on 在区间 [min(0, tolerance), max(0, tolerance)] 内时，右侧行被视为与左侧行匹配。tolerance 可以是

• 负数，此时会发生向后连接（join-as-of-past）（当且仅当 tolerance <= right.on - left.on <= 0 时匹配）；

• 正数，此时会发生向前连接（join-as-of-future）（当且仅当 0 <= right.on - left.on <= tolerance 时匹配）；

• 或零，此时会发生精确连接（join-as-of-exact）（当且仅当 right.on == left.on 时匹配）。

容差的单位与“on”键相同。

right_onstr 或 list[str], 默认 None

右侧数据集中应在连接操作中作为“on”键使用的列。当为 None 时，使用与左侧数据集相同的键名。

right_bystr 或 list[str], 默认 None

右侧数据集中应在连接操作中作为“by”键使用的列。当为 None 时，使用与左侧数据集相同的键名。

返回：

InMemoryDataset

partition_expression

对所有此数据集查看的数据评估为 true 的表达式。

replace_schema(self, Schema schema)

返回此数据集的副本，并使用不同的模式。

副本将查看相同的片段。如果新模式与原始数据集的模式不兼容，则会引发错误。

参数:

schemaSchema

新的数据集模式。

scanner(self, 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)

针对数据集构建扫描操作。

数据不会立即加载。相反，这将生成一个扫描器（Scanner），它公开了进一步的操作（例如，将所有数据加载为表，计算行数）。

有关更多信息，请参阅 Scanner.from_dataset() 方法。

参数:

columnslist of str, default 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

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

返回：

scannerScanner

示例

>>> import pyarrow as pa
>>> table = pa.table({'year': [2020, 2022, 2021, 2022, 2019, 2021],
...                   '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, "dataset_scanner.parquet")

>>> import pyarrow.dataset as ds
>>> dataset = ds.dataset("dataset_scanner.parquet")

选择列子集

>>> dataset.scanner(columns=["year", "n_legs"]).to_table()
pyarrow.Table
year: int64
n_legs: int64
----
year: [[2020,2022,2021,2022,2019,2021]]
n_legs: [[2,2,4,4,5,100]]

使用表达式投影选定的列

>>> dataset.scanner(columns={
...     "n_legs_uint": ds.field("n_legs").cast("uint8"),
... }).to_table()
pyarrow.Table
n_legs_uint: uint8
----
n_legs_uint: [[2,2,4,4,5,100]]

扫描时过滤行

>>> dataset.scanner(filter=ds.field("year") > 2020).to_table()
pyarrow.Table
year: int64
n_legs: int64
animal: string
----
year: [[2022,2021,2022,2021]]
n_legs: [[2,4,4,100]]
animal: [["Parrot","Dog","Horse","Centipede"]]

schema

完整数据集的公共模式

sort_by(self, sorting, **kwargs)

按一列或多列对数据集进行排序。

参数:

sortingstr 或 list[tuple(name, order)]

用于排序的列名（升序），或多个排序条件的列表，其中每个条目都是一个包含列名和排序顺序（“ascending”或“descending”）的元组

**kwargsdict, 可选

附加排序选项。由 SortOptions 允许。

返回：

InMemoryDataset

根据排序键排序的新数据集。

take(self, indices, 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)

按索引选择数据行。

参数:

indicesArray 或 array-like

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

columnslist of str, default 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

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

返回：

tableTable

to_batches(self, 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)

将数据集读取为具体化的记录批次（materialized record batches）。

参数:

columnslist of str, default 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

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

返回：

record_batchesiterator of RecordBatch

to_table(self, 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)

将数据集读取为 Arrow 表。

请注意，此方法将从数据集中读取所有选定的数据到内存中。

参数:

columnslist of str, default 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

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

返回：

tableTable