数据集文档

表格类

数据集

加入 Hugging Face 社区

并获得增强的文档体验

在模型、数据集和 Spaces 上协作

通过加速推理获得更快的示例

切换文档主题

开始使用

表格类

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

Table

class 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。

这些方法的实现在子类中有所不同。

validate

( *args **kwargs )

参数

full (bool, 默认为 False) — 如果为 True，则运行昂贵的检查，否则仅运行廉价的检查。

引发

pa.lib.ArrowInvalid

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

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

默认情况下，仅运行廉价的验证检查。传递 `full=True` 以进行彻底的验证检查（可能为 `O(n)`）。

equals

( *args **kwargs ) → bool

参数

other (Table) — 要比较的 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 或 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) — 将带 null 值的整数转换为对象。
date_as_object (bool, 默认为 True) — 将日期转换为对象。如果为 False，则转换为 datetime64[ns] dtype。
timestamp_as_object (bool, 默认为 False) — 将非纳秒时间戳 (np.datetime64) 转换为对象。如果您有不适合纳秒时间戳正常日期范围（公元 1678 年 - 公元 2262 年）的时间戳，这将非常有用。如果为 False，所有时间戳都将转换为 datetime64[ns] dtype。
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 时，为每列生成一个内部“块”。虽然这可以暂时减少内存，但请注意，各种 pandas 操作可能会触发“合并”，这可能会使内存使用量激增。
self_destruct (bool, 默认为 False) — 实验性功能：如果为 True，则尝试在将 Arrow 对象转换为 pandas 时，释放原始 Arrow 内存。如果在调用带有此选项的 to_pandas 后使用该对象，程序将会崩溃。
types_mapper (function, 默认为 None) — 一个将 pyarrow DataType 映射到 pandas ExtensionDtype 的函数。这可以用于覆盖内置 pyarrow 类型的默认 pandas 类型转换，或者在 Table 架构中缺少 pandas_metadata 的情况下使用。该函数接收一个 pyarrow DataType，并应返回一个 pandas ExtensionDtype，或者如果应为该类型使用默认转换，则返回 None。如果您有字典映射，则可以将 dict.get 作为函数传递。

返回

pandas.Series 或 pandas.DataFrame

pandas.Series 或 pandas.DataFrame，取决于对象类型

转换为 pandas 兼容的 NumPy 数组或 DataFrame，视情况而定。

to_string

( *args **kwargs )

field

( *args **kwargs )

参数

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

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

column

( *args **kwargs )

参数

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

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

itercolumns

( *args **kwargs )

按数字顺序迭代所有列。

schema

( )

表及其列的架构。

columns

( )

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

num_columns

( )

此表中的列数。

num_rows

( )

此表中的行数。

由于表的定义，所有列都具有相同的行数。

shape

( ) → (int, int)

返回

(int, int)

行数和列数。

表的维度：（#行，#列）。

nbytes

( )

表元素消耗的总字节数。

InMemoryTable

class datasets.table.InMemoryTable

( table: Table )

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

对其进行 pickle 操作会复制所有使用内存的数据。它的实现很简单，直接使用底层的 pyarrow Table 方法。

这与 MemoryMapped 表不同，对于后者，pickle 操作不会复制内存中的所有数据。对于 MemoryMapped，取消 pickle 操作实际上是从磁盘重新加载表。

当数据适合内存时，必须使用 InMemoryTable，而 MemoryMapped 保留用于大于内存的数据，或者当您希望应用程序的内存占用保持较低时使用。

validate

( *args **kwargs )

参数

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

引发

pa.lib.ArrowInvalid

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

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

默认情况下，仅运行廉价的验证检查。传递 `full=True` 以进行彻底的验证检查（可能为 `O(n)`）。

equals

( *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 或 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) — 将带有 null 值的整数转换为对象。
date_as_object (bool, 默认为 True) — 将日期转换为对象。如果为 False，则转换为 datetime64[ns] dtype。
timestamp_as_object (bool, 默认为 False) — 将非纳秒时间戳 (np.datetime64) 转换为对象。如果您有时间戳不符合纳秒时间戳的正常日期范围（1678 CE-2262 CE），这将非常有用。如果为 False，则所有时间戳都将转换为 datetime64[ns] dtype。
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 时，为每列生成一个内部“块”。虽然这可以暂时减少内存，但请注意，各种 pandas 操作可能会触发“合并”，从而可能增加内存使用量。
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 )

field

( *args **kwargs )

参数

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

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

column

( *args **kwargs )

参数

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

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

itercolumns

( *args **kwargs )

按数字顺序迭代所有列。

schema

( )

表及其列的架构。

columns

( )

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

num_columns

( )

此表中的列数。

num_rows

( )

此表中的行数。

由于表的定义，所有列都具有相同的行数。

shape

( ) → (int, int)

返回

(int, int)

行数和列数。

表的维度：（#行，#列）。

nbytes

( )

表元素消耗的总字节数。

column_names

( )

表的列名。

slice

( offset = 0 length = None )

参数

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

计算此表的零拷贝切片。

filter

( *args **kwargs )

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

flatten

( *args **kwargs )

参数

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

扁平化此表。每个具有结构类型的列都会被扁平化为每个结构字段一列。其他列保持不变。

combine_chunks

( *args **kwargs )

参数

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

通过合并此表拥有的数据块来创建一个新表。

每个列的 ChunkedArray 中的所有底层数据块都被连接成零个或一个数据块。

cast

( *args **kwargs )

参数

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

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

replace_schema_metadata

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

参数

metadata (dict, 默认为 None) —

返回

datasets.table.Table

shallow_copy

实验性功能：通过将模式键值元数据替换为指示的新元数据（可以是 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

添加了传递列的新表。

在指定位置向表中添加列。

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

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

不包含该列的新表。

创建删除了指定列的新表。

set_column

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

参数

i (int) — 列要放置的位置索引。
field_ (Union[str, pyarrow.Field]) — 如果传递的是字符串，则类型将从列数据中推断出来。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列数据。

返回

datasets.table.Table

设置了传递列的新表。

在指定位置替换表中的列。

rename_columns

( *args **kwargs )

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

select

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

参数

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

返回

datasets.table.Table

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

选择表的列。

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

drop

( *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 的预期模式。这可以用于指示列的类型，如果我们无法自动推断它。如果传递，输出将完全具有此模式。模式中指定的列如果未在 DataFrame 列或其索引中找到，则会引发错误。 DataFrame 中未在模式中指定的其他列或索引级别将被忽略。
preserve_index (bool, 可选) — 是否将索引作为额外的列存储在结果 Table 中。默认值为 None 将索引存储为列，但 RangeIndex 除外，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 推断出来的。对于非对象 Series，NumPy dtype 将转换为其 Arrow 等效项。对于 object，我们需要通过查看此 Series 中的 Python 对象来猜测数据类型。

请注意，object dtype 的 Series 没有携带足够的信息来始终产生有意义的 Arrow 类型。如果我们无法推断类型，例如，因为 DataFrame 的长度为 0 或 Series 仅包含 None/nan 对象，则类型设置为 null。通过构造显式模式并将其传递给此函数可以避免此行为。

示例

>>> 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) — 创建的表格的模式。如果未传递，则必须传递 names。
metadata (Union[dict, Mapping], 默认为 None) — 模式的可选元数据（如果已推断）。

从 Arrow 数组构造表格。

from_pydict

( *args **kwargs )

参数

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

从 Arrow 数组或列构造表格。

from_batches

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

参数

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

返回

datasets.table.Table

从 Arrow RecordBatches 的序列或迭代器构造表格。

MemoryMappedTable

class datasets.table.MemoryMappedTable

( table: Table path: str replays: Optional = None )

当表格不使用用户的 RAM 而是从磁盘加载数据时，该表格被称为内存映射。

对其进行 pickle 操作不会将数据复制到内存中。相反，只有内存映射的 arrow 文件的路径以及在从磁盘重新加载表格时要“重放”的转换列表会被 pickle。

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

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

当数据适合内存时，必须使用 InMemoryTable，而 MemoryMapped 保留用于大于内存的数据，或者当您希望应用程序的内存占用保持较低时使用。

validate

( *args **kwargs )

参数

full (bool, 默认为 False) — 如果为 True，则运行昂贵的检查，否则仅进行廉价的检查。

引发

pa.lib.ArrowInvalid

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

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

默认情况下，仅运行廉价的验证检查。传递 `full=True` 以进行彻底的验证检查（可能为 `O(n)`）。

equals

( *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 或 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）— 将带有 null 值的整数强制转换为对象。
date_as_object (bool, 默认为 True）— 将日期强制转换为对象。如果为 False，则转换为 datetime64[ns] dtype。
timestamp_as_object (bool, 默认为 False）— 将非纳秒时间戳 (np.datetime64) 强制转换为对象。如果您有时间戳不适合纳秒时间戳的正常日期范围（公元 1678 年 - 公元 2262 年），这将非常有用。如果为 False，则所有时间戳都将转换为 datetime64[ns] dtype。
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 时，为每列生成一个内部“块”。虽然这可以暂时减少内存，但请注意，各种 pandas 操作可能会触发“合并”，从而可能使内存使用量激增。
self_destruct (bool, 默认为 False）— 实验性：如果为 True，则尝试在将 Arrow 对象转换为 pandas 时释放原始 Arrow 内存。如果在调用带有此选项的 to_pandas 后使用该对象，则程序将崩溃。
types_mapper (function, 默认为 None）— 将 pyarrow DataType 映射到 pandas ExtensionDtype 的函数。这可用于覆盖内置 pyarrow 类型的默认 pandas 类型转换，或者在 Table 模式中缺少 pandas_metadata 的情况下使用。该函数接收一个 pyarrow DataType，并应返回 pandas ExtensionDtype；如果应使用该类型的默认转换，则返回 None。如果您有字典映射，则可以将 dict.get 作为函数传递。

返回

pandas.Series 或 pandas.DataFrame

pandas.Series 或 pandas.DataFrame，取决于对象类型

转换为 pandas 兼容的 NumPy 数组或 DataFrame，视情况而定。

to_string

( *args **kwargs )

field

( *args **kwargs )

参数

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

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

column

( *args **kwargs )

参数

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

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

itercolumns

( *args **kwargs )

按数字顺序迭代所有列。

schema

( )

表及其列的架构。

columns

( )

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

num_columns

( )

此表中的列数。

num_rows

( )

此表中的行数。

由于表的定义，所有列都具有相同的行数。

shape

( ) → (int, int)

返回

(int, int)

行数和列数。

表的维度：（#行，#列）。

nbytes

( )

表元素消耗的总字节数。

column_names

( )

表的列名。

slice

( offset = 0 length = None )

参数

offset (int, defaults to 0) — 从表开始到切片的偏移量。
length (int, defaults to None) — 切片的长度 (默认是从偏移量开始到表尾)。

计算此表的零拷贝切片。

filter

( *args **kwargs )

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

flatten

( *args **kwargs )

参数

memory_pool (MemoryPool, defaults to None) — 用于内存分配，如果需要，否则使用默认池。

扁平化此表。每个具有结构类型的列都会被扁平化为每个结构字段一列。其他列保持不变。

combine_chunks

( *args **kwargs )

参数

memory_pool (MemoryPool, defaults to None) — 用于内存分配，如果需要，否则使用默认池。

通过合并此表拥有的数据块来创建一个新表。

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

cast

( *args **kwargs )

参数

target_schema (Schema) — 要转换成的模式，字段的名称和顺序必须匹配。
safe (bool, defaults to True) — 检查溢出或其他不安全的转换。

将表值转换为另一个模式

replace_schema_metadata

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

参数

metadata (dict, defaults to None) —

返回

datasets.table.Table

shallow_copy

实验性功能：通过将模式键值元数据替换为指示的新元数据（可以为 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

添加了传递列的新表。

在指定位置向表中添加列。

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

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

不包含该列的新表。

创建删除了指定列的新表。

set_column

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

参数

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

返回

datasets.table.Table

设置了传递列的新表。

在指定位置替换表中的列。

rename_columns

( *args **kwargs )

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

select

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

参数

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

返回

datasets.table.Table

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

选择表的列。

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

drop

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

参数

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

返回

datasets.table.Table

不包含这些列的新表。

引发

KeyError

KeyError — : 如果任何传递的列名不存在。

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

from_file

( filename: str replays = None )

ConcatenationTable

class datasets.table.ConcatenationTable

( table: Table blocks: List )

该表来自于几个被称为“块 (blocks)”的表的连接。它支持在轴 0（追加行）和轴 1（追加列）上进行连接。

底层的表被称为“块 (blocks)”，可以是 InMemoryTable 或 MemoryMappedTable 对象。这允许组合来自内存或内存映射的表。当 ConcatenationTable 被 pickle 序列化时，每个块也会被 pickle 序列化。

InMemoryTable 对象通过复制内存中的所有数据来进行 pickle 序列化。
MemoryMappedTable 对象在 pickle 序列化时不会将数据复制到内存中。相反，只有内存映射的 Arrow 文件的路径会被 pickle 序列化，以及在从磁盘重新加载表时“重放 (replays)”的转换列表。

它的实现需要分别存储每个块。blocks 属性存储块的列表的列表。第一个轴沿着轴 0 连接表（即追加行），而第二个轴沿着轴 1 连接表（即追加列）。

如果在轴 0 上连接时缺少某些列，它们将被空值填充。这是通过使用 pyarrow.concat_tables(tables, promote=True) 完成的。

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

validate

( *args **kwargs )

参数

full (bool, 默认为 False) — 如果为 True，则运行开销大的检查，否则只运行廉价的检查。

引发

pa.lib.ArrowInvalid

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

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

默认情况下，仅运行廉价的验证检查。传递 `full=True` 以进行彻底的验证检查（可能为 `O(n)`）。

equals

( *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 或 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] dtype。
timestamp_as_object (bool, 默认为 False) — 将非纳秒时间戳 (np.datetime64) 转换为对象。如果您有不适合纳秒时间戳正常日期范围（1678 CE-2262 CE）的时间戳，这将非常有用。如果为 False，则所有时间戳都将转换为 datetime64[ns] dtype。
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 模式中缺少 pandas_metadata 时使用。该函数接收一个 pyarrow DataType，并应返回一个 pandas ExtensionDtype，或者如果应使用该类型的默认转换，则返回 None。如果您有字典映射，则可以将 dict.get 作为函数传递。

返回

pandas.Series 或 pandas.DataFrame

pandas.Series 或 pandas.DataFrame，取决于对象类型

转换为 pandas 兼容的 NumPy 数组或 DataFrame，视情况而定。

to_string

( *args **kwargs )

field

( *args **kwargs )

参数

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

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

column

( *args **kwargs )

参数

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

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

itercolumns

( *args **kwargs )

按数字顺序迭代所有列。

schema

( )

表及其列的架构。

columns

( )

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

num_columns

( )

此表中的列数。

num_rows

( )

此表中的行数。

由于表的定义，所有列都具有相同的行数。

shape

( ) → (int, int)

返回

(int, int)

行数和列数。

表的维度：（#行，#列）。

nbytes

( )

表元素消耗的总字节数。

column_names

( )

表的列名。

slice

( offset = 0 length = None )

参数

offset (int, defaults to 0) — 从表开始到切片的偏移量。
length (int, defaults to None) — 切片的长度（默认为从偏移量开始到表尾）。

计算此表的零拷贝切片。

filter

( mask *args **kwargs )

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

flatten

( *args **kwargs )

参数

memory_pool (MemoryPool, defaults to None) — 用于内存分配，如果需要，否则使用默认池。

扁平化此表。每个具有结构类型的列都会被扁平化为每个结构字段一列。其他列保持不变。

combine_chunks

( *args **kwargs )

参数

memory_pool (MemoryPool, defaults to None) — 用于内存分配，如果需要，否则使用默认池。

通过合并此表拥有的数据块来创建一个新表。

每个列的 ChunkedArray 中的所有底层数据块都被连接成零个或一个数据块。

cast

( target_schema *args **kwargs )

参数

target_schema (Schema) — 要转换成的 Schema，字段的名称和顺序必须匹配。
safe (bool, defaults to True) — 检查溢出或其他不安全的转换。

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

replace_schema_metadata

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

参数

metadata (dict, defaults to None) —

返回

datasets.table.Table

shallow_copy

实验性功能：通过将模式键值元数据替换为指示的新元数据（可以是 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

添加了传递列的新表。

在指定位置向表中添加列。

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

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

不包含该列的新表。

创建删除了指定列的新表。

set_column

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

参数

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

返回

datasets.table.Table

设置了传递列的新表。

在指定位置替换表中的列。

rename_columns

( names *args **kwargs )

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

select

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

参数

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

返回

datasets.table.Table

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

选择表的列。

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

drop

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

参数

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

返回

datasets.table.Table

不包含这些列的新表。

引发

KeyError

KeyError — : 如果任何传递的列名不存在。

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

from_blocks

( blocks: TableBlockContainer )

from_tables

( tables: List axis: int = 0 )

参数

tables (list of Table or list of pyarrow.Table) — 表格列表。
axis ({0, 1}, 默认为 0，表示按行) — 连接轴，其中 0 表示按行（垂直），1 表示按列（水平）。

在 1.6.0 版本中添加

从表格列表创建 ConcatenationTable。

Utils

datasets.table.concat_tables

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

参数

tables (list of 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]

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

获取表格加载的缓存文件。当表格的部分内容通过内存映射从磁盘加载时，会使用缓存文件。

< > 在 GitHub 上更新

←加载方法实用工具→