Hugging Face's logo

数据集文档

表格类

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

表格类

每个 Dataset 对象都由 PyArrow 表格支持。表格可以从磁盘（内存映射）或内存中加载。有几种表格类型可用，它们都继承自 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) — 要比较的表格。
  • check_metadata bool, 默认为 False) — 是否也应检查模式元数据是否相等。

返回

bool

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

to_batches

< >

( *args **kwargs )

参数

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

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

to_pydict

< >

( *args **kwargs ) → dict

返回

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, 默认为 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 CE-2262 CE) 时，此选项很有用。如果设置为 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 类型的转换，或者在 Table 模式中缺少 pandas_metadata 时使用的默认 pandas 类型。此函数接收一个 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 块的最大大小。根据单个列的块布局，各个块可能会更小。

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

to_pydict

< >

( *args **kwargs ) → dict

返回

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, 默认为 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 模式中缺少 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) — 用于内存分配，如果需要，否则使用默认池。

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

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

实验性功能：通过用指示的新元数据（可以为 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

添加了传递列的新表格。

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

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

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 表的预期模式。 这可用于指示列的类型（如果我们无法自动推断）。 如果传递，则输出将具有完全相同的模式。 如果在 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 表格。

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

从 Arrow 数组构造表格。

from_pydict

< >

( *args **kwargs )

参数

  • mapping (Union[dict, Mapping]) — 字符串到 Arrays 或 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: typing.Optional[list[tuple[str, tuple, dict]]] = None )

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

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

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

这与 InMemoryTable 表格不同，对于 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` 块的最大大小。单个块可能会更小，具体取决于各个列的块布局。

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

to_pydict

< >

( *args **kwargs ) → dict

返回

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`，默认为 `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 架构中缺少 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) — 用于内存分配，如果需要，否则使用默认池。

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

combine_chunks

< >

( *args **kwargs )

参数

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

通过组合此表格拥有的块来创建新表格。

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

cast

< >

( *args **kwargs )

参数

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

将表格值转换为另一个 schema

replace_schema_metadata

< >

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

参数

  • metadata (dict, defaults to 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

添加了传递列的新表格。

在列的末尾追加列。

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 )

该表来自几个称为块的表的拼接。它支持在轴 0（追加行）和轴 1（追加列）上进行拼接。

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

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

它的实现需要单独存储每个块。 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 块的最大大小。各个块可能会更小，具体取决于各个列的块布局。

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

to_pydict

< >

( *args **kwargs ) → dict

返回

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, 默认为 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

< >

( mask *args **kwargs )

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

flatten

< >

( *args **kwargs )

参数

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

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

combine_chunks

< >

( *args **kwargs )

参数

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

通过组合此表格拥有的块来创建新表格。

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

cast

< >

( target_schema *args **kwargs )

参数

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

将表格值转换为另一个 schema。

replace_schema_metadata

< >

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

参数

  • metadata (dict, defaults to 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

添加了传递列的新表格。

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

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

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}, defaults to 0, meaning over rows) — 要连接的轴，其中 0 表示按行（垂直）连接，1 表示按列（水平）连接。

    在 1.6.0 版本中添加

Create ConcatenationTable from list of tables.

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 上更新

←加载方法 实用工具→