Datasets 文档

Table Classes

数据集

加入 Hugging Face 社区

并获得增强的文档体验

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

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

切换文档主题

开始使用

表类

每个 Dataset 对象都由一个 PyArrow 表支持。表可以从磁盘（内存映射）或内存中加载。有几种表类型可用，它们都继承自 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, defaults to False) — 如果为 True，运行昂贵的检查，否则只运行廉价的检查。

引发

pa.lib.ArrowInvalid

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

执行验证检查。如果验证失败，则抛出异常。

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

equals

( *args **kwargs ) → bool

参数

other (Table) — 用于比较的表。
check_metadata bool, defaults to False) — 是否也应检查模式元数据的相等性。

返回

布尔值

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

to_batches

( *args **kwargs )

参数

max_chunksize (int, defaults to None) — RecordBatch 块的最大大小。根据单个列的块布局，单个块可能更小。

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

to_pydict

( *args **kwargs ) → dict

返回

字典

将 Table 转换为 dict 或 OrderedDict。

to_pandas

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

参数

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

返回

pandas.Series or 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 中时，它被称为内存中表（in-memory table）。

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

这与 MemoryMapped 表不同，后者在进行 pickle 操作时不会复制所有数据到内存中。对于 MemoryMapped 表，反序列化时会从磁盘重新加载表。

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

validate

( *args **kwargs )

参数

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

引发

pa.lib.ArrowInvalid

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

执行验证检查。如果验证失败，则抛出异常。

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

equals

( *args **kwargs ) → bool

参数

other (Table) — 用于比较的表。
check_metadata bool, defaults to False) — 是否也应检查模式元数据的相等性。

返回

布尔值

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

to_batches

( *args **kwargs )

参数

max_chunksize (int, defaults to None) — RecordBatch 块的最大大小。根据单个列的块布局，单个块可能更小。

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

to_pydict

( *args **kwargs ) → dict

返回

字典

将 Table 转换为 dict 或 OrderedDict。

to_pandas

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

参数

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

返回

pandas.Series or 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) — 切片长度（默认是从偏移量开始到表尾）。

计算此表的零拷贝切片。

过滤器

( *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) — 要转换到的模式，字段名称和顺序必须匹配。
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 )

创建一个将列重命名为指定名称的新表。

选择

( targs **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, optional) — The expected schema of the Arrow Table. This can be used to indicate the type of columns if we cannot infer it automatically. If passed, the output will have exactly this schema. Columns specified in the schema that are not found in the DataFrame columns or its index will raise an error. Additional columns or index levels in the DataFrame which are not specified in the schema will be ignored.
preserve_index (bool, optional) — Whether to store the index as an additional column in the resulting Table. The default of None will store the index as a column, except for RangeIndex which is stored as metadata only. Use preserve_index=True to force it to be stored as a column.
nthreads (int, defaults to None (may use up to system CPU count threads)) — If greater than 1, convert columns to Arrow in parallel using indicated number of threads.
columns (List[str], optional) — List of column to be converted. If None, use all columns.
safe (bool, defaults to True) — Check for overflows or other unsafe conversions,

返回

datasets.table.Table

Convert pandas.DataFrame to an Arrow Table.

The column types in the resulting Arrow Table are inferred from the dtypes of the pandas.Series in the DataFrame. In the case of non-object Series, the NumPy dtype is translated to its Arrow equivalent. In the case of object, we need to guess the datatype by looking at the Python objects in this Series.

Be aware that Series of the object dtype don’t carry enough information to always lead to a meaningful Arrow type. In the case that we cannot infer a type, e.g. because the DataFrame is of length 0 or the Series only contains None/nan objects, the type is set to null. This behavior can be avoided by constructing an explicit schema and passing it to this function.

示例

>>> 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]]) — Equal-length arrays that should form the table.
names (List[str], optional) — Names for the table columns. If not passed, schema must be passed.
schema (Schema, defaults to None) — Schema for the created table. If not passed, names must be passed.
metadata (Union[dict, Mapping], defaults to None) — Optional metadata for the schema (if inferred).

Construct a Table from Arrow arrays.

from_pydict

( *args **kwargs )

参数

mapping (Union[dict, Mapping]) — A mapping of strings to Arrays or Python lists.
schema (Schema, defaults to None) — If not passed, will be inferred from the Mapping values
metadata (Union[dict, Mapping], defaults to None) — Optional metadata for the schema (if inferred).

Construct a Table from Arrow arrays or columns.

from_batches

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

参数

batches (Union[Sequence[pyarrow.RecordBatch], Iterator[pyarrow.RecordBatch]]) — Sequence of RecordBatch to be converted, all schemas must be equal.
schema (Schema, defaults to None) — If not passed, will be inferred from the first RecordBatch.

返回

datasets.table.Table

Construct a Table from a sequence or iterator of Arrow RecordBatches.

MemoryMappedTable

class datasets.table.MemoryMappedTable

( table: Table path: str replays: typing.Optional[list[tuple[str, tuple, dict]]] = None )

The table is said memory mapped when it doesn’t use the user’s RAM but loads the data from the disk instead.

Pickling it doesn’t copy the data into memory. Instead, only the path to the memory mapped arrow file is pickled, as well as the list of transforms to “replay” when reloading the table from the disk.

Its implementation requires to store an history of all the transforms that were applied to the underlying pyarrow Table, so that they can be “replayed” when reloading the Table from the disk.

This is different from the InMemoryTable table, for which pickling does copy all the data in memory.

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

validate

( *args **kwargs )

参数

full (bool, defaults to False) — If True, run expensive checks, otherwise cheap checks only.

引发

pa.lib.ArrowInvalid

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

执行验证检查。如果验证失败，则抛出异常。

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

equals

( *args **kwargs ) → bool

参数

other (Table) — Table to compare against.
check_metadata bool, defaults to False) — Whether schema metadata equality should be checked as well.

返回

布尔值

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

to_batches

( *args **kwargs )

参数

max_chunksize (int, defaults to None) — Maximum size for RecordBatch chunks. Individual chunks may be smaller depending on the chunk layout of individual columns.

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

to_pydict

( *args **kwargs ) → dict

返回

字典

将 Table 转换为 dict 或 OrderedDict。

to_pandas

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

参数

memory_pool (MemoryPool, defaults to None) — Arrow MemoryPool to use for allocations. Uses the default memory pool is not passed.
strings_to_categorical (bool, defaults to False) — Encode string (UTF8) and binary types to pandas.Categorical.
categories (list, defaults to empty) — List of fields that should be returned as pandas.Categorical. Only applies to table-like data structures.
zero_copy_only (bool, defaults to False) — Raise an ArrowException if this function call would require copying the underlying data.
integer_object_nulls (bool, defaults to False) — Cast integers with nulls to objects.
date_as_object (bool, defaults to True) — Cast dates to objects. If False, convert to datetime64[ns] dtype.
timestamp_as_object (bool, defaults to False) — Cast non-nanosecond timestamps (np.datetime64) to objects. This is useful if you have timestamps that don’t fit in the normal date range of nanosecond timestamps (1678 CE-2262 CE). If False, all timestamps are converted to datetime64[ns] dtype.
use_threads (bool, defaults to True) — Whether to parallelize the conversion using multiple threads.
deduplicate_objects (bool, defaults to False) — Do not create multiple copies Python objects when created, to save on memory use. Conversion will be slower.
ignore_metadata (bool, defaults to False) — If True, do not use the ‘pandas’ metadata to reconstruct the DataFrame index, if present.
safe (bool, defaults to True) — For certain data types, a cast is needed in order to store the data in a pandas DataFrame or Series (e.g. timestamps are always stored as nanoseconds in pandas). This option controls whether it is a safe cast or not.
split_blocks (bool, defaults to False) — If True, generate one internal “block” for each column when creating a pandas.DataFrame from a RecordBatch or Table. While this can temporarily reduce memory note that various pandas operations can trigger “consolidation” which may balloon memory use.
self_destruct (bool, defaults to False) — EXPERIMENTAL: If True, attempt to deallocate the originating Arrow memory while converting the Arrow object to pandas. If you use the object after calling to_pandas with this option it will crash your program.
types_mapper (function, defaults to None) — A function mapping a pyarrow DataType to a pandas ExtensionDtype. This can be used to override the default pandas type for conversion of built-in pyarrow types or in absence of pandas_metadata in the Table schema. The function receives a pyarrow DataType and is expected to return a pandas ExtensionDtype or None if the default conversion should be used for that type. If you have a dictionary mapping, you can pass dict.get as function.

返回

pandas.Series or pandas.DataFrame

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

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

to_string

( *args **kwargs )

field

( *args **kwargs )

参数

i (Union[int, str]) — The index or name of the field to retrieve.

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

column

( *args **kwargs )

参数

i (Union[int, str]) — The index or name of the column to retrieve.

按列名或数字索引选择列。

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) — 切片的长度（默认为从偏移量开始到表尾）。

计算此表的零拷贝切片。

过滤器

( *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) — 用于内存分配（如果需要），否则使用默认内存池。

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

All the underlying chunks in the ChunkedArray of each column are concatenated into zero or one chunk.

cast

( *args **kwargs )

参数

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

Cast table values to another schema

replace_schema_metadata

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

参数

metadata (dict, defaults to None) —

返回

datasets.table.Table

shallow_copy

EXPERIMENTAL: Create shallow copy of table by replacing schema key-value metadata with the indicated new metadata (which may be None, which deletes any existing metadata.

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 )

创建一个将列重命名为指定名称的新表。

选择

( targs **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（附加列）进行连接。

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

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

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

如果在沿轴0连接时缺少某些列，则会用空值填充。这是使用 pyarrow.concat_tables(tables, promote=True) 完成的。

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

validate

( *args **kwargs )

参数

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

引发

pa.lib.ArrowInvalid

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

执行验证检查。如果验证失败，则抛出异常。

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

equals

( *args **kwargs ) → bool

参数

other (Table) — 要比较的表。
check_metadata bool, defaults to False) — 是否也应检查 schema 元数据是否相等。

返回

布尔值

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

to_batches

( *args **kwargs )

参数

max_chunksize (int, defaults to None) — RecordBatch 块的最大大小。根据单个列的块布局，单个块可能更小。

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

to_pydict

( *args **kwargs ) → dict

返回

字典

将 Table 转换为 dict 或 OrderedDict。

to_pandas

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

参数

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

返回

pandas.Series or 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) — 切片的长度（默认是从偏移量开始到表格结束）。

计算此表的零拷贝切片。

过滤器

( mask *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

( 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 )

创建一个将列重命名为指定名称的新表。

选择

( 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 表示按列（水平）连接。

Added in 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}, defaults to 0, meaning over rows) — 沿哪个轴进行连接，0 表示按行（垂直）连接，1 表示按列（水平）连接。

Added in 1.6.0

返回

datasets.table.Table

如果输入表格数量 > 1，则返回的表格为 datasets.table.ConcatenationTable。否则，如果只有一个表格，则按原样返回。

Concatenate tables.

datasets.table.list_table_cache_files

( table: Table ) → List[str]

返回

List[str]

A list of paths to the cache files loaded by the table.

获取由表格加载的缓存文件。缓存文件用于表格部分数据来自磁盘且通过内存映射加载的情况。

在 GitHub 上更新

←加载方法 Utilities→

© . This site is unofficial and not affiliated with Hugging Face, Inc.