Datasets documentation

表格类

Datasets

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

表格类

每个 Dataset 对象都由一个 PyArrow Table 提供支持。 Table 可以从磁盘（内存映射）加载，也可以加载到内存中。有多种 Table 类型可用，它们都继承自 table.Table。

表格

类 datasets.table.Table

( table: Table )

通过组合方式封装 pyarrow Table。这是 InMemoryTable、MemoryMappedTable 和 ConcatenationTable 的基类。

它实现了 pyarrow Table 类的所有基本属性/方法，但不包括 Table 转换：slice, filter, flatten, combine_chunks, cast, add_column, append_column, remove_column, set_column, rename_columns 和 drop。

这些方法的实现因子类而异。

验证

( *args**kwargs )

参数

full (bool，默认为 False) — 如果为 True，则运行开销较大的检查；否则仅运行开销较小的检查。

引发

pa.lib.ArrowInvalid

pa.lib.ArrowInvalid — 如果验证失败

执行验证检查。如果验证失败，则会引发异常。

默认情况下仅运行低成本的验证检查。传入 full=True 以执行全面的验证检查（可能为 O(n)）。

等于

( *args**kwargs ) → bool

参数

other (Table) — 用于比较的表。
check_metadata bool，默认为 False) — 是否同时检查架构元数据的相等性。

返回值

bool

检查两个表的内容是否相等。

to_batches

( *args**kwargs )

参数

max_chunksize (int，默认为 None) — RecordBatch 块的最大大小。根据各个列的块布局，单个块可能会更小。

将 Table 转换为（连续的）RecordBatch 对象列表。

to_pydict

( *args**kwargs ) → dict

返回值

dict

将 Table 转换为 dict 或 OrderedDict。

to_pandas

( *args**kwargs ) → pandas.Series or pandas.DataFrame

参数

memory_pool (MemoryPool，默认为 None) — 用于分配的 Arrow MemoryPool。如果未传入，则使用默认内存池。
strings_to_categorical (bool，默认为 False) — 将字符串（UTF8）和二进制类型编码为 pandas.Categorical。
categories (list，默认为 empty) — 应作为 pandas.Categorical 返回的字段列表。仅适用于表格型数据结构。
zero_copy_only (bool，默认为 False) — 如果此函数调用需要复制底层数据，则抛出 ArrowException。
integer_object_nulls (bool，默认为 False) — 将包含空值的整数转换为对象。
date_as_object (bool，默认为 True) — 将日期转换为对象。如果为 False，则转换为 datetime64[ns] 数据类型。
timestamp_as_object (bool，默认为 False) — 将非纳秒时间戳（np.datetime64）转换为对象。如果您拥有超出纳秒时间戳正常日期范围（公元 1678 年至公元 2262 年）的时间戳，此操作非常有用。如果为 False，所有时间戳都将转换为 datetime64[ns] 数据类型。
use_threads (bool，默认为 True) — 是否使用多个线程并行化转换过程。
deduplicate_objects (bool，默认为 False) — 在创建时不生成多个 Python 对象副本，以节省内存使用。转换速度会变慢。
ignore_metadata (bool，默认为 False) — 如果为 True，则不使用 'pandas' 元数据来重建 DataFrame 索引（如果存在）。
safe (bool，默认为 True) — 对于某些数据类型，需要执行类型转换才能将数据存储在 pandas DataFrame 或 Series 中（例如，pandas 中的时间戳始终以纳秒为单位存储）。此选项用于控制该类型转换是否为安全转换。
split_blocks (bool，默认为 False) — 如果为 True，则从 RecordBatch 或 Table 创建 pandas.DataFrame 时，会为每一列生成一个内部“block”。虽然这可以暂时减少内存，但请注意，各种 pandas 操作可能会触发“consolidation”，从而导致内存使用量激增。
self_destruct (bool，默认为 False) — 实验性功能：如果为 True，则在将 Arrow 对象转换为 pandas 时，尝试释放源 Arrow 内存。如果在调用 to_pandas 并使用此选项后继续使用该对象，将导致程序崩溃。
types_mapper (function，默认为 None) — 一个将 pyarrow DataType 映射到 pandas ExtensionDtype 的函数。可用于覆盖内置 pyarrow 类型转换的默认 pandas 类型，或在 Table schema 中缺少 pandas_metadata 时使用。该函数接收一个 pyarrow DataType，并预期返回一个 pandas ExtensionDtype；如果应使用默认转换，则返回 None。如果您有一个字典映射，可以将 dict.get 作为函数传入。

返回值

pandas.Series 或 pandas.DataFrame

根据对象类型，返回 pandas.Series 或 pandas.DataFrame

将其转换为兼容 pandas 的 NumPy 数组或 DataFrame（视情况而定）。

to_string

( *args**kwargs )

字段

( *args**kwargs )

参数

i (Union[int, str]) — 要检索的字段索引或名称。

通过列名或数字索引选择模式字段。

列

( *args**kwargs )

参数

i (Union[int, str]) — 要检索的列的索引或名称。

通过列名或数字索引选择列。

itercolumns

( *args**kwargs )

按数值顺序迭代所有列。

模式

( )

该表及其列的结构。

列

( )

按数字顺序排列的所有列的列表。

num_columns

( )

此表格中的列数。

num_rows

( )

此表中的行数。

根据表的定义，所有列的行数都相同。

形状

( ) → (int, int)

返回值

(int, int)

行数和列数。

表格的维度：(#rows, #columns)。

字节数

( )

表中元素消耗的总字节数。

InMemoryTable

类 datasets.table.InMemoryTable

( table: Table )

当表被加载到用户的 RAM 中时，我们称其为内存中的表。

使用 Pickling 确实会通过内存复制所有数据。其实现很简单，直接使用了底层的 pyarrow Table 方法。

这与MemoryMapped表不同，后者的 pickle 操作不会将内存中的所有数据复制一份。对于MemoryMapped，unpickle 操作会从磁盘重新加载该表。

当数据能够放入内存时，必须使用 InMemoryTable；而 MemoryMapped 则用于数据大于内存的情况，或者当你希望应用程序的内存占用保持较低时。

验证

( *args**kwargs )

参数

full (bool，默认为 False) — 如果为 True，则运行开销较大的检查；否则仅运行开销较小的检查。

引发

pa.lib.ArrowInvalid

pa.lib.ArrowInvalid — 如果验证失败

执行验证检查。如果验证失败，则会引发异常。

默认情况下仅运行低成本的验证检查。传入 full=True 以执行全面的验证检查（可能为 O(n)）。

等于

( *args**kwargs ) → bool

参数

other (Table) — 用于比较的表。
check_metadata bool，默认为 False) — 是否同时检查架构元数据的相等性。

返回值

bool

检查两个表的内容是否相等。

to_batches

( *args**kwargs )

参数

max_chunksize (int，默认为 None) — RecordBatch 块的最大大小。根据各个列的块布局，单个块可能会更小。

将 Table 转换为（连续的）RecordBatch 对象列表。

to_pydict

( *args**kwargs ) → dict

返回值

dict

将 Table 转换为 dict 或 OrderedDict。

to_pandas

( *args**kwargs ) → pandas.Series or pandas.DataFrame

参数

memory_pool (MemoryPool，默认为 None) — 用于分配的 Arrow MemoryPool。如果未传入，则使用默认内存池。
strings_to_categorical (bool，默认为 False) — 将字符串（UTF8）和二进制类型编码为 pandas.Categorical。
categories (list，默认为 empty) — 应作为 pandas.Categorical 返回的字段列表。仅适用于表格型数据结构。
zero_copy_only (bool，默认为 False) — 如果此函数调用需要复制底层数据，则抛出 ArrowException。
integer_object_nulls (bool，默认为 False) — 将包含空值的整数转换为对象。
date_as_object (bool，默认为 True) — 将日期转换为对象。如果为 False，则转换为 datetime64[ns] 数据类型。
timestamp_as_object (bool，默认为 False) — 将非纳秒时间戳（np.datetime64）转换为对象。如果您拥有超出纳秒时间戳正常日期范围（公元 1678 年至公元 2262 年）的时间戳，此操作非常有用。如果为 False，所有时间戳都将转换为 datetime64[ns] 数据类型。
use_threads (bool，默认为 True) — 是否使用多个线程并行化转换过程。
deduplicate_objects (bool，默认为 False) — 在创建时不生成多个 Python 对象副本，以节省内存使用。转换速度会变慢。
ignore_metadata (bool，默认为 False) — 如果为 True，则不使用 'pandas' 元数据来重建 DataFrame 索引（如果存在）。
safe (bool，默认为 True) — 对于某些数据类型，需要执行类型转换才能将数据存储在 pandas DataFrame 或 Series 中（例如，pandas 中的时间戳始终以纳秒为单位存储）。此选项用于控制该类型转换是否为安全转换。
split_blocks (bool，默认为 False) — 如果为 True，则从 RecordBatch 或 Table 创建 pandas.DataFrame 时，会为每一列生成一个内部“block”。虽然这可以暂时减少内存，但请注意，各种 pandas 操作可能会触发“consolidation”，从而导致内存使用量激增。
self_destruct (bool，默认为 False) — 实验性功能：如果为 True，则在将 Arrow 对象转换为 pandas 时，尝试释放源 Arrow 内存。如果在调用 to_pandas 并使用此选项后继续使用该对象，将导致程序崩溃。
types_mapper (function，默认为 None) — 一个将 pyarrow DataType 映射到 pandas ExtensionDtype 的函数。可用于覆盖内置 pyarrow 类型转换的默认 pandas 类型，或在 Table schema 中缺少 pandas_metadata 时使用。该函数接收一个 pyarrow DataType，并预期返回一个 pandas ExtensionDtype；如果应使用默认转换，则返回 None。如果您有一个字典映射，可以将 dict.get 作为函数传入。

返回值

pandas.Series 或 pandas.DataFrame

根据对象类型，返回 pandas.Series 或 pandas.DataFrame

将其转换为兼容 pandas 的 NumPy 数组或 DataFrame（视情况而定）。

to_string

( *args**kwargs )

字段

( *args**kwargs )

参数

i (Union[int, str]) — 要检索的字段索引或名称。

通过列名或数字索引选择模式字段。

列

( *args**kwargs )

参数

i (Union[int, str]) — 要检索的列的索引或名称。

通过列名或数字索引选择列。

itercolumns

( *args**kwargs )

按数值顺序迭代所有列。

模式

( )

该表及其列的结构。

列

( )

按数字顺序排列的所有列的列表。

num_columns

( )

此表格中的列数。

num_rows

( )

此表中的行数。

根据表的定义，所有列的行数都相同。

形状

( ) → (int, int)

返回值

(int, int)

行数和列数。

表格的维度：(#rows, #columns)。

字节数

( )

表中元素消耗的总字节数。

column_names

( )

表格列的名称。

切片

( offset = 0length = None )

参数

offset (int, 默认为 0) — 从表格起始位置到切片的偏移量。
length (int，默认为 None) — 切片长度（默认从 offset 开始直到表格末尾）。

计算此 Table 的零拷贝切片。

过滤

( *args**kwargs )

从 Table 中筛选记录。有关完整用法，请参阅 pyarrow.compute.filter。

展平

( *args**kwargs )

参数

memory_pool（MemoryPool，默认为 None）— 用于内存分配，如果必需，否则使用默认池。

展平此表。每个结构体类型的列都会被展平为每个结构体字段对应的一列。其他列保持不变。

combine_chunks

( *args**kwargs )

参数

memory_pool（MemoryPool，默认为 None）— 用于内存分配，如果必需，否则使用默认池。

通过合并此表中的各个块来创建新表。

每列的 ChunkedArray 中所有底层块都会被拼接成零个或一个块。

cast

( *args**kwargs )

参数

target_schema (Schema) — 要转换到的 Schema，字段的名称和顺序必须匹配。
safe (bool，默认为 True) — 检查是否存在溢出或其他不安全的转换。

将表值转换为另一种模式。

replace_schema_metadata

( *args**kwargs ) → datasets.table.Table

参数

metadata（dict，默认为 None） —

返回值

datasets.table.Table

shallow_copy

实验性功能：通过用指定的新元数据（可以为 None，这将删除任何现有元数据）替换 schema 键值元数据，创建表的浅拷贝。

add_column

( *args**kwargs ) → datasets.table.Table

参数

i (int) — 用于放置该列的索引。
field_ (Union[str, pyarrow.Field]) — 如果传入字符串，则从列数据中推断类型。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回值

datasets.table.Table

添加了传入列的新表。

在指定位置向 Table 添加列。

返回一个添加了该列的新表，原始表对象保持不变。

append_column

( *args**kwargs ) → datasets.table.Table

参数

field_ (Union[str, pyarrow.Field]) — 如果传入字符串，则从列数据中推断类型。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回值

datasets.table.Table

添加了传入列的新表。

在列的末尾追加列。

remove_column

( *args**kwargs ) → datasets.table.Table

参数

i (int) — 要删除的列索引。

返回值

datasets.table.Table

没有该列的新表格。

创建一个新的 Table，其中移除了指定的列。

set_column

( *args**kwargs ) → datasets.table.Table

参数

i (int) — 用于放置该列的索引。
field_ (Union[str, pyarrow.Field]) — 如果传入字符串，则从列数据中推断类型。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回值

datasets.table.Table

包含已传递列集的新表。

替换位于指定位置的 Table 中的列。

rename_columns

( *args**kwargs )

创建新表，并将列重命名为提供的名称。

选择

( *args**kwargs ) → datasets.table.Table

参数

columns (Union[List[str], List[int]]) — 要选择的列名或整数索引。

返回值

datasets.table.Table

包含指定列的新表，并保留元数据。

选择表格的列。

返回一个包含指定列的新表，并保留元数据。

丢弃

( *args**kwargs ) → datasets.table.Table

参数

columns (List[str]) — 引用现有列的字段名列表。

返回值

datasets.table.Table

没有这些列的新表格。

引发

KeyError

KeyError — ：如果传入的列名中有任何一个不存在。

删除一个或多个列并返回一个新表。

from_file

( filename: str )

from_buffer

( buffer: Buffer )

from_pandas

( *args**kwargs ) → datasets.table.Table

参数

df (pandas.DataFrame) —
schema (pyarrow.Schema, 可选) — Arrow Table 的预期 schema。如果无法自动推断列的类型，可以使用此参数来指定列的类型。如果传入该参数，输出将具有完全一致的 schema。schema 中指定但在 DataFrame 的列或其索引中未找到的列将引发错误。DataFrame 中未在 schema 中指定的额外列或索引级别将被忽略。
preserve_index (bool, 可选) — 是否将索引作为额外列存储在生成的 Table 中。默认值 None 会将索引存储为列，但 RangeIndex 除外，后者仅作为元数据存储。使用 preserve_index=True 可强制将其存储为列。
nthreads (int，默认为 None（最多可使用系统 CPU 数量的线程）） — 如果大于 1，则使用指定数量的线程并行将列转换为 Arrow 格式。
columns (List[str]，可选) — 要转换的列列表。如果为 None，则使用所有列。
safe (bool，默认为 True) — 检查是否存在溢出或其他不安全的转换，

返回值

datasets.table.Table

将 pandas.DataFrame 转换为 Arrow Table。

结果中 Arrow Table 的列类型是根据 DataFrame 中 pandas.Series 的 dtypes 推断出来的。对于非 object 类型的 Series，NumPy dtype 会被转换为其对应的 Arrow 类型。对于 object 类型，我们需要通过查看该 Series 中的 Python 对象来猜测其数据类型。

请注意，object 类型的 Series 不包含足够的信息，因此不一定能推导出有意义的 Arrow 类型。如果无法推断类型，例如 DataFrame 长度为 0，或 Series 仅包含 None/nan 对象，则类型会被设置为 null。可以通过构建显式 schema 并将其传递给此函数来避免这种行为。

示例：

>>> import pandas as pd
>>> import pyarrow as pa
>>> df = pd.DataFrame({
    ...     'int': [1, 2],
    ...     'str': ['a', 'b']
    ... })
>>> pa.Table.from_pandas(df)
<pyarrow.lib.Table object at 0x7f05d1fb1b40>

from_arrays

( *args**kwargs )

参数

arrays (List[Union[pyarrow.Array, pyarrow.ChunkedArray]]) — 长度相等的数组，用于构成表。
names (List[str]，可选) — 表格列的名称。如果未传入，则必须传入 schema。
schema (Schema，默认为 None) — 所创建表的 Schema。如果未传入，则必须传入名称。
metadata (Union[dict, Mapping]，默认为 None) — 模式（如果推断得出）的可选元数据。

从 Arrow 数组构建 Table。

from_pydict

( *args**kwargs )

参数

mapping (Union[dict, Mapping]) — 从字符串到数组或 Python 列表的映射。
schema (Schema，默认为 None) — 如果未传入，将从 Mapping 值中推断
metadata (Union[dict, Mapping]，默认为 None) — 模式（如果推断得出）的可选元数据。

从 Arrow 数组或列构建 Table。

from_batches

( *args**kwargs ) → datasets.table.Table

参数

batches (Union[Sequence[pyarrow.RecordBatch], Iterator[pyarrow.RecordBatch]]) — 要转换的 RecordBatch 序列，所有 schema 必须相等。
schema (Schema，默认为 None) — 如果未传入，将从第一个 RecordBatch 中推断得出。

返回值

datasets.table.Table

从 RecordBatches 序列或迭代器构建 Table。

MemoryMappedTable

类 datasets.table.MemoryMappedTable

( table: Tablepath: strreplays: typing.Optional[list[tuple[str, tuple, dict]]] = None )

当表不使用用户的 RAM，而是直接从磁盘加载数据时，我们称该表为内存映射（memory mapped）。

序列化操作并不会将数据复制到内存中。相反，它只序列化内存映射 arrow 文件的路径，以及从磁盘重新加载表时需要“重放”的转换列表。

其实现需要存储应用于底层 pyarrow Table 的所有转换的历史记录，以便在从磁盘重新加载 Table 时能够“重放”这些转换。

这与 InMemoryTable 表不同，后者的 pickle 操作会复制内存中的所有数据。

当数据能够放入内存时，必须使用 InMemoryTable；而 MemoryMapped 则用于数据大于内存的情况，或者当你希望应用程序的内存占用保持较低时。

验证

( *args**kwargs )

参数

full (bool，默认为 False) — 如果为 True，则运行开销较大的检查；否则仅运行开销较小的检查。

引发

pa.lib.ArrowInvalid

pa.lib.ArrowInvalid — 如果验证失败

执行验证检查。如果验证失败，则会引发异常。

默认情况下仅运行低成本的验证检查。传入 full=True 以执行全面的验证检查（可能为 O(n)）。

等于

( *args**kwargs ) → bool

参数

other (Table) — 用于比较的表。
check_metadata bool，默认为 False) — 是否同时检查架构元数据的相等性。

返回值

bool

检查两个表的内容是否相等。

to_batches

( *args**kwargs )

参数

max_chunksize (int，默认为 None) — RecordBatch 块的最大大小。根据各个列的块布局，单个块可能会更小。

将 Table 转换为（连续的）RecordBatch 对象列表。

to_pydict

( *args**kwargs ) → dict

返回值

dict

将 Table 转换为 dict 或 OrderedDict。

to_pandas

( *args**kwargs ) → pandas.Series or pandas.DataFrame

参数

memory_pool (MemoryPool，默认为 None) — 用于分配的 Arrow MemoryPool。如果未传入，则使用默认内存池。
strings_to_categorical (bool，默认为 False) — 将字符串（UTF8）和二进制类型编码为 pandas.Categorical。
categories (list，默认为 empty) — 应作为 pandas.Categorical 返回的字段列表。仅适用于表格型数据结构。
zero_copy_only (bool，默认为 False) — 如果此函数调用需要复制底层数据，则抛出 ArrowException。
integer_object_nulls (bool，默认为 False) — 将包含空值的整数转换为对象。
date_as_object (bool，默认为 True) — 将日期转换为对象。如果为 False，则转换为 datetime64[ns] 数据类型。
timestamp_as_object (bool，默认为 False) — 将非纳秒时间戳（np.datetime64）转换为对象。如果您拥有超出纳秒时间戳正常日期范围（公元 1678 年至公元 2262 年）的时间戳，此操作非常有用。如果为 False，所有时间戳都将转换为 datetime64[ns] 数据类型。
use_threads (bool，默认为 True) — 是否使用多个线程并行化转换过程。
deduplicate_objects (bool，默认为 False) — 在创建时不生成多个 Python 对象副本，以节省内存使用。转换速度会变慢。
ignore_metadata (bool，默认为 False) — 如果为 True，则不使用 'pandas' 元数据来重建 DataFrame 索引（如果存在）。
safe (bool，默认为 True) — 对于某些数据类型，需要执行类型转换才能将数据存储在 pandas DataFrame 或 Series 中（例如，pandas 中的时间戳始终以纳秒为单位存储）。此选项用于控制该类型转换是否为安全转换。
split_blocks (bool，默认为 False) — 如果为 True，则从 RecordBatch 或 Table 创建 pandas.DataFrame 时，会为每一列生成一个内部“block”。虽然这可以暂时减少内存，但请注意，各种 pandas 操作可能会触发“consolidation”，从而导致内存使用量激增。
self_destruct (bool，默认为 False) — 实验性功能：如果为 True，则在将 Arrow 对象转换为 pandas 时，尝试释放源 Arrow 内存。如果在调用 to_pandas 并使用此选项后继续使用该对象，将导致程序崩溃。
types_mapper (function，默认为 None) — 一个将 pyarrow DataType 映射到 pandas ExtensionDtype 的函数。可用于覆盖内置 pyarrow 类型转换的默认 pandas 类型，或在 Table schema 中缺少 pandas_metadata 时使用。该函数接收一个 pyarrow DataType，并预期返回一个 pandas ExtensionDtype；如果应使用默认转换，则返回 None。如果您有一个字典映射，可以将 dict.get 作为函数传入。

返回值

pandas.Series 或 pandas.DataFrame

根据对象类型，返回 pandas.Series 或 pandas.DataFrame

将其转换为兼容 pandas 的 NumPy 数组或 DataFrame（视情况而定）。

to_string

( *args**kwargs )

字段

( *args**kwargs )

参数

i (Union[int, str]) — 要检索的字段索引或名称。

通过列名或数字索引选择模式字段。

列

( *args**kwargs )

参数

i (Union[int, str]) — 要检索的列的索引或名称。

通过列名或数字索引选择列。

itercolumns

( *args**kwargs )

按数值顺序迭代所有列。

模式

( )

该表及其列的结构。

列

( )

按数字顺序排列的所有列的列表。

num_columns

( )

此表格中的列数。

num_rows

( )

此表中的行数。

根据表的定义，所有列的行数都相同。

形状

( ) → (int, int)

返回值

(int, int)

行数和列数。

表格的维度：(#rows, #columns)。

字节数

( )

表中元素消耗的总字节数。

column_names

( )

表格列的名称。

切片

( offset = 0length = None )

参数

offset (int, 默认为 0) — 从表格起始位置到切片的偏移量。
length (int，默认为 None) — 切片长度（默认从 offset 开始直到表格末尾）。

计算此 Table 的零拷贝切片。

过滤

( *args**kwargs )

从 Table 中筛选记录。有关完整用法，请参阅 pyarrow.compute.filter。

展平

( *args**kwargs )

参数

memory_pool（MemoryPool，默认为 None）— 用于内存分配，如果必需，否则使用默认池。

展平此表。每个结构体类型的列都会被展平为每个结构体字段对应的一列。其他列保持不变。

combine_chunks

( *args**kwargs )

参数

memory_pool（MemoryPool，默认为 None）— 用于内存分配，如果必需，否则使用默认池。

通过合并此表中的各个块来创建新表。

每列的 ChunkedArray 中所有底层块都会被拼接成零个或一个块。

cast

( *args**kwargs )

参数

target_schema (Schema) — 要转换到的 Schema，字段的名称和顺序必须匹配。
safe (bool，默认为 True) — 检查是否存在溢出或其他不安全的转换。

将表值转换为另一种模式

replace_schema_metadata

( *args**kwargs ) → datasets.table.Table

参数

metadata（dict，默认为 None） —

返回值

datasets.table.Table

shallow_copy

实验性功能：通过替换 schema 键值元数据为指定的新元数据（可以为 None，这将删除任何现有元数据）来创建表的浅拷贝

add_column

( *args**kwargs ) → datasets.table.Table

参数

i (int) — 用于放置该列的索引。
field_ (Union[str, pyarrow.Field]) — 如果传入字符串，则从列数据中推断类型。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回值

datasets.table.Table

添加了传入列的新表。

在指定位置向 Table 添加列。

返回一个添加了该列的新表，原始表对象保持不变。

append_column

( *args**kwargs ) → datasets.table.Table

参数

field_ (Union[str, pyarrow.Field]) — 如果传入字符串，则从列数据中推断类型。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回值

datasets.table.Table

添加了传入列的新表。

在列的末尾追加列。

remove_column

( *args**kwargs ) → datasets.table.Table

参数

i (int) — 要删除的列索引。

返回值

datasets.table.Table

没有该列的新表格。

创建一个新的 Table，其中移除了指定的列。

set_column

( *args**kwargs ) → datasets.table.Table

参数

i (int) — 用于放置该列的索引。
field_ (Union[str, pyarrow.Field]) — 如果传入字符串，则从列数据中推断类型。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回值

datasets.table.Table

包含已传递列集的新表。

替换位于指定位置的 Table 中的列。

rename_columns

( *args**kwargs )

创建新表，并将列重命名为提供的名称。

选择

( *args**kwargs ) → datasets.table.Table

参数

columns (Union[List[str], List[int]]) — 要选择的列名或整数索引。

返回值

datasets.table.Table

包含指定列的新表，并保留元数据。

选择表格的列。

返回一个包含指定列的新表，并保留元数据。

丢弃

( *args**kwargs ) → datasets.table.Table

参数

columns (List[str]) — 引用现有列的字段名列表。

返回值

datasets.table.Table

没有这些列的新表格。

引发

KeyError

KeyError — ：如果传入的列名中有任何一个不存在。

删除一个或多个列并返回一个新表。

from_file

( filename: strreplays = None )

ConcatenationTable

类 datasets.table.ConcatenationTable

( table: Tableblocks: list )

该表格由多个称为块的表格拼接而成。它支持在轴 0（追加行）和轴 1（追加列）上进行拼接。

底层的表被称为“块”，可以是 InMemoryTable 或 MemoryMappedTable 对象。这使得可以组合来自内存或内存映射的表。当 ConcatenationTable 被 pickle 时，每个块都会被 pickle：

InMemoryTable 对象通过复制内存中的所有数据进行 pickle 序列化。
MemoryMappedTable 对象在序列化时不会将数据复制到内存中。相反，序列化的内容仅包括内存映射 arrow 文件的路径，以及从磁盘重新加载表时需要“重放”的转换列表。

其实现要求单独存储每个块。 blocks 属性存储一个块列表的列表。第一个轴沿轴 0 拼接表格（即追加行），而第二个轴沿轴 1 拼接表格（即追加列）。

在沿 axis 0 进行拼接时，如果某些列缺失，则用 null 值填充。此操作通过 pyarrow.concat_tables(tables, promote=True) 实现。

您可以通过访问 ConcatenationTable.table 属性来访问完全合并后的表格，并通过访问 ConcatenationTable.blocks 属性来访问各个块。

验证

( *args**kwargs )

参数

full (bool，默认为 False) — 如果为 True，则运行开销较大的检查；否则仅运行开销较小的检查。

引发

pa.lib.ArrowInvalid

pa.lib.ArrowInvalid — 如果验证失败

执行验证检查。如果验证失败，则会引发异常。

默认情况下仅运行低成本的验证检查。传入 full=True 以执行全面的验证检查（可能为 O(n)）。

等于

( *args**kwargs ) → bool

参数

other (Table) — 用于比较的表。
check_metadata bool，默认为 False) — 是否同时检查架构元数据的相等性。

返回值

bool

检查两个表的内容是否相等。

to_batches

( *args**kwargs )

参数

max_chunksize (int，默认为 None) — RecordBatch 块的最大大小。根据各个列的块布局，单个块可能会更小。

将 Table 转换为（连续的）RecordBatch 对象列表。

to_pydict

( *args**kwargs ) → dict

返回值

dict

将 Table 转换为 dict 或 OrderedDict。

to_pandas

( *args**kwargs ) → pandas.Series or pandas.DataFrame

参数

memory_pool (MemoryPool，默认为 None) — 用于分配的 Arrow MemoryPool。如果未传入，则使用默认内存池。
strings_to_categorical (bool，默认为 False) — 将字符串（UTF8）和二进制类型编码为 pandas.Categorical。
categories (list，默认为 empty) — 应作为 pandas.Categorical 返回的字段列表。仅适用于表格型数据结构。
zero_copy_only (bool，默认为 False) — 如果此函数调用需要复制底层数据，则抛出 ArrowException。
integer_object_nulls (bool，默认为 False) — 将包含空值的整数转换为对象。
date_as_object (bool，默认为 True) — 将日期转换为对象。如果为 False，则转换为 datetime64[ns] 数据类型。
timestamp_as_object (bool，默认为 False) — 将非纳秒时间戳（np.datetime64）转换为对象。如果您拥有超出纳秒时间戳正常日期范围（公元 1678 年至公元 2262 年）的时间戳，此操作非常有用。如果为 False，所有时间戳都将转换为 datetime64[ns] 数据类型。
use_threads (bool，默认为 True) — 是否使用多个线程并行化转换过程。
deduplicate_objects (bool，默认为 False) — 在创建时不生成多个 Python 对象副本，以节省内存使用。转换速度会变慢。
ignore_metadata (bool，默认为 False) — 如果为 True，则不使用 'pandas' 元数据来重建 DataFrame 索引（如果存在）。
safe (bool，默认为 True) — 对于某些数据类型，需要执行类型转换才能将数据存储在 pandas DataFrame 或 Series 中（例如，pandas 中的时间戳始终以纳秒为单位存储）。此选项用于控制该类型转换是否为安全转换。
split_blocks (bool，默认为 False) — 如果为 True，则从 RecordBatch 或 Table 创建 pandas.DataFrame 时，会为每一列生成一个内部“block”。虽然这可以暂时减少内存，但请注意，各种 pandas 操作可能会触发“consolidation”，从而导致内存使用量激增。
self_destruct (bool，默认为 False) — 实验性功能：如果为 True，则在将 Arrow 对象转换为 pandas 时，尝试释放源 Arrow 内存。如果在调用 to_pandas 并使用此选项后继续使用该对象，将导致程序崩溃。
types_mapper (function，默认为 None) — 一个将 pyarrow DataType 映射到 pandas ExtensionDtype 的函数。可用于覆盖内置 pyarrow 类型转换的默认 pandas 类型，或在 Table schema 中缺少 pandas_metadata 时使用。该函数接收一个 pyarrow DataType，并预期返回一个 pandas ExtensionDtype；如果应使用默认转换，则返回 None。如果您有一个字典映射，可以将 dict.get 作为函数传入。

返回值

pandas.Series 或 pandas.DataFrame

根据对象类型，返回 pandas.Series 或 pandas.DataFrame

将其转换为兼容 pandas 的 NumPy 数组或 DataFrame（视情况而定）。

to_string

( *args**kwargs )

字段

( *args**kwargs )

参数

i (Union[int, str]) — 要检索的字段索引或名称。

通过列名或数字索引选择模式字段。

列

( *args**kwargs )

参数

i (Union[int, str]) — 要检索的列的索引或名称。

通过列名或数字索引选择列。

itercolumns

( *args**kwargs )

按数值顺序迭代所有列。

模式

( )

该表及其列的结构。

列

( )

按数字顺序排列的所有列的列表。

num_columns

( )

此表格中的列数。

num_rows

( )

此表中的行数。

根据表的定义，所有列的行数都相同。

形状

( ) → (int, int)

返回值

(int, int)

行数和列数。

表格的维度：(#rows, #columns)。

字节数

( )

表中元素消耗的总字节数。

column_names

( )

表格列的名称。

切片

( offset = 0length = None )

参数

offset (int, 默认为 0) — 从表格起始位置到切片的偏移量。
length (int，默认为 None) — 切片长度（默认从 offset 开始直到表格末尾）。

计算此 Table 的零拷贝切片。

过滤

( mask*args**kwargs )

从 Table 中筛选记录。有关完整用法，请参阅 pyarrow.compute.filter。

展平

( *args**kwargs )

参数

memory_pool（MemoryPool，默认为 None）— 用于内存分配，如果必需，否则使用默认池。

展平此表。每个结构体类型的列都会被展平为每个结构体字段对应的一列。其他列保持不变。

combine_chunks

( *args**kwargs )

参数

memory_pool（MemoryPool，默认为 None）— 用于内存分配，如果必需，否则使用默认池。

通过合并此表中的各个块来创建新表。

每列的 ChunkedArray 中所有底层块都会被拼接成零个或一个块。

cast

( target_schema*args**kwargs )

参数

target_schema (Schema) — 要转换到的 Schema，字段的名称和顺序必须匹配。
safe (bool，默认为 True) — 检查是否存在溢出或其他不安全的转换。

将表值转换为另一种模式。

replace_schema_metadata

( *args**kwargs ) → datasets.table.Table

参数

metadata（dict，默认为 None） —

返回值

datasets.table.Table

shallow_copy

实验性功能：通过用指定的新元数据（可以为 None，这将删除任何现有元数据）替换 schema 键值元数据，创建表的浅拷贝。

add_column

( *args**kwargs ) → datasets.table.Table

参数

i (int) — 用于放置该列的索引。
field_ (Union[str, pyarrow.Field]) — 如果传入字符串，则从列数据中推断类型。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回值

datasets.table.Table

添加了传入列的新表。

在指定位置向 Table 添加列。

返回一个添加了该列的新表，原始表对象保持不变。

append_column

( *args**kwargs ) → datasets.table.Table

参数

field_ (Union[str, pyarrow.Field]) — 如果传入字符串，则从列数据中推断类型。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回值

datasets.table.Table

添加了传入列的新表。

在列的末尾追加列。

remove_column

( i*args**kwargs ) → datasets.table.Table

参数

i (int) — 要删除的列索引。

返回值

datasets.table.Table

没有该列的新表格。

创建一个新的 Table，其中移除了指定的列。

set_column

( *args**kwargs ) → datasets.table.Table

参数

i (int) — 用于放置该列的索引。
field_ (Union[str, pyarrow.Field]) — 如果传入字符串，则从列数据中推断类型。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回值

datasets.table.Table

包含已传递列集的新表。

替换位于指定位置的 Table 中的列。

rename_columns

( names*args**kwargs )

创建新表，并将列重命名为提供的名称。

选择

( columns*args**kwargs ) → datasets.table.Table

参数

columns (Union[List[str], List[int]]) — 要选择的列名或整数索引。

返回值

datasets.table.Table

包含指定列的新表，并保留元数据。

选择表格的列。

返回一个包含指定列的新表，并保留元数据。

丢弃

( columns*args**kwargs ) → datasets.table.Table

参数

columns (List[str]) — 引用现有列的字段名列表。

返回值

datasets.table.Table

没有这些列的新表格。

引发

KeyError

KeyError — ：如果传入的列名中有任何一个不存在。

删除一个或多个列并返回一个新表。

from_blocks

( blocks: ~TableBlockContainer )

from_tables

( tables: listaxis: int = 0 )

参数

tables（Table 列表或 pyarrow.Table 列表）— 表格列表。
axis ({0, 1}, 默认为 0, ，表示沿行方向）— 要拼接的轴，其中 0 表示沿行方向（垂直）拼接， 1 表示沿列方向（水平）拼接。

1.6.0 版本新增

从表列表创建 ConcatenationTable。

工具

datasets.table.concat_tables

( tables: listaxis: int = 0 ) → datasets.table.Table

参数

tables（Table 列表）— 要拼接的表格列表。
axis ({0, 1}, 默认为 0, ，表示沿行方向）— 要拼接的轴，其中 0 表示沿行方向（垂直）拼接， 1 表示沿列方向（水平）拼接。

1.6.0 版本新增

返回值

datasets.table.Table

如果输入表的数量 > 1，则返回的表是一个 datasets.table.ConcatenationTable。否则，如果只有一个表，则直接返回该表。

拼接表格。

datasets.table.list_table_cache_files

( table: Table ) → List[str]

返回值

List[str]

由该表格加载的缓存文件路径列表。

获取由该表加载的缓存文件。当表的部分数据通过内存映射从磁盘读取时，会使用缓存文件。

Update on GitHub

←加载方法实用工具→