表类

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

Table

class datasets.table.Table

( table: Table )

通过组合方式包装一个 pyarrow 表。这是 InMemoryTable、MemoryMappedTable 和 ConcatenationTable 的基类。

它实现了 pyarrow 表类的所有基本属性/方法，但表的转换方法除外：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) — 用于比较的表。
check_metadata bool，默认为 False) — 是否也检查模式元数据的相等性。

布尔值

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

to_batches

< 来源 >

( *args **kwargs )

参数

max_chunksize (int，默认为 None) — RecordBatch 块的最大大小。单个块的大小可能更小，具体取决于单个列的块布局。

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

to_pydict

< 来源 >

( *args **kwargs ) → dict

字典

将表转换为 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，默认为 空列表) — 应作为 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 时，为每列生成一个内部“块”。虽然这可以暂时减少内存，但请注意，各种 pandas 操作可能会触发“合并”，这可能会导致内存使用量激增。
self_destruct (bool，默认为 False) — 实验性功能：如果为 True，在将 Arrow 对象转换为 pandas 时尝试释放原始 Arrow 内存。如果您在使用此选项调用 to_pandas 后再使用该对象，将会导致程序崩溃。
types_mapper (function，默认为 None) — 一个将 pyarrow DataType 映射到 pandas ExtensionDtype 的函数。这可用于覆盖内置 pyarrow 类型的默认 pandas 类型转换，或在表模式中缺少 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 中时，该表被称为内存中的表。

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

这与 MemoryMapped 表不同，对于后者，Pickling 不会将所有数据复制到内存中。对于 MemoryMapped，unpickling 操作会从磁盘重新加载表。

当数据适合内存时，必须使用 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) — 是否也检查 schema 元数据是否相等。

布尔值

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

to_batches

< 源码 >

( *args **kwargs )

参数

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

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

to_pydict

< 源码 >

( *args **kwargs ) → dict

字典

将表转换为 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, 默认为 空列表) — 应作为 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 年至 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 类型转换，或者在表 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) — 切片的长度（默认为从偏移量开始直到表尾）。

计算此表的零拷贝切片。

过滤器

< 源码 >

( *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) — 要转换到的 schema，字段的名称和顺序必须匹配。
safe (bool, 默认为 True) — 检查溢出或其他不安全的转换。

将表值转换为另一个 schema。

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

添加了传入列的新表。

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

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

append_column

< 源码 >

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

参数

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

datasets.table.Table

添加了传入列的新表。

在列的末尾追加列。

数据集

表类

Table

class datasets.table.Table

validate

equals

to_batches

to_pydict

to_pandas

to_string

field

column

itercolumns

schema

columns

num_columns

num_rows

shape

nbytes

InMemoryTable

class datasets.table.InMemoryTable

validate

equals

to_batches

to_pydict

to_pandas

to_string

field

column

itercolumns

schema

columns

num_columns

num_rows

shape

nbytes

column_names

slice

过滤器

flatten

combine_chunks

cast

replace_schema_metadata

add_column

append_column

remove_column

set_column

rename_columns

选择

drop

from_file

from_buffer

from_pandas

from_arrays

from_pydict

from_batches

MemoryMappedTable

class datasets.table.MemoryMappedTable

validate

equals

to_batches

to_pydict

to_pandas

to_string

field

column

itercolumns

schema

columns

num_columns

num_rows

shape

nbytes

column_names

slice

过滤器

flatten

combine_chunks

cast

replace_schema_metadata