# 表格类 每个 `Dataset` 对象都由一个 PyArrow Table 提供支持。Table 可以从磁盘（内存映射）加载，也可以加载到内存中。有多种 Table 类型可用，它们都继承自 [table.Table](/docs/datasets/v5.2.0/zh/package_reference/table_classes#datasets.table.Table)。 ## 表格[[datasets.table.Table]] #### datasets.table.Table[[datasets.table.Table]] ```python datasets.table.Table(table: Table) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L210) 通过组合方式封装 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[[datasets.table.Table.validate]] ```python validate(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L235) **参数：** full (`bool`，默认为 `False`)：如果为 `True`，则运行开销较大的检查，否则仅运行开销较小的检查。 **引发：** ``pa.lib.ArrowInvalid`` - ``pa.lib.ArrowInvalid`` -- 如果验证失败 执行验证检查。如果验证失败，则会引发异常。 默认情况下仅运行低成本的验证检查。传入 `full=True` 以执行全面的验证检查（可能为 `O(n)`）。 #### equals[[datasets.table.Table.equals]] ```python equals(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L251) **参数：** other ([表格](/docs/datasets/v5.2.0/zh/package_reference/table_classes#datasets.table.Table))：用于比较的表格。 check_metadata `bool`，默认为 `False`) : 是否还应检查架构元数据的相等性。 **返回：** `bool` 检查两个表的内容是否相等。 #### to_batches[[datasets.table.Table.to_batches]] ```python to_batches(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L268) **参数：** max_chunksize (`int`，默认为 `None`)：`RecordBatch` 块的最大大小。根据各个列的块布局，单个块可能会更小。 **返回：** `List[pyarrow.RecordBatch]` 将 Table 转换为（连续的）`RecordBatch` 对象列表。 #### to_pydict[[datasets.table.Table.to_pydict]] ```python to_pydict(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L282) **返回：** `dict` 将 Table 转换为 `dict` 或 `OrderedDict`。 #### to_pandas[[datasets.table.Table.to_pandas]] ```python to_pandas(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L300) **参数：** 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 时，会为每一列生成一个内部“块”。虽然这可以暂时减少内存，但请注意，各种 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[[datasets.table.Table.to_string]] ```python to_string(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L362) #### field[[datasets.table.Table.field]] ```python field(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L381) **参数：** i (`Union[int, str]`) : 要检索的字段索引或名称。 **返回：** `pyarrow.Field` 通过列名或数字索引选择模式字段。 #### 列[[datasets.table.Table.column]] ```python column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L394) **参数：** i (`Union[int, str]`) : 要检索的列的索引或名称。 **返回：** `pyarrow.ChunkedArray` 通过列名或数字索引选择列。 #### itercolumns[[datasets.table.Table.itercolumns]] ```python itercolumns(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L407) **返回值：** `pyarrow.ChunkedArray` 按数值顺序迭代所有列。 #### schema[[datasets.table.Table.schema]] ```python schema() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L416) **返回：** `pyarrow.Schema` 该表及其列的结构。 #### 列[[datasets.table.Table.columns]] ```python columns() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L426) **返回：** `List[pa.ChunkedArray]` 按数字顺序排列的所有列的列表。 #### num_columns[[datasets.table.Table.num_columns]] ```python num_columns() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L436) **返回：** int 此表格中的列数。 #### num_rows[[datasets.table.Table.num_rows]] ```python num_rows() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L446) **返回：** int 此表中的行数。 根据表的定义，所有列的行数都相同。 #### shape[[datasets.table.Table.shape]] ```python shape() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L459) **返回：** `(int, int)` 行数和列数。 表格的维度：(#rows, #columns)。 #### nbytes[[datasets.table.Table.nbytes]] ```python nbytes() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L469) 表中元素消耗的总字节数。 ## InMemoryTable[[datasets.table.InMemoryTable]] #### datasets.table.InMemoryTable[[datasets.table.InMemoryTable]] ```python datasets.table.InMemoryTable(table: Table) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L695) 当表被加载到用户的 RAM 中时，我们称其为内存中的表。 使用 Pickling 确实会通过内存复制所有数据。其实现很简单，直接使用了底层的 pyarrow Table 方法。 这与`MemoryMapped`表不同，后者的 pickle 操作不会将内存中的所有数据复制一份。对于`MemoryMapped`，unpickle 操作会从磁盘重新加载该表。 当数据能够放入内存时，必须使用 `InMemoryTable`；而 `MemoryMapped` 则用于数据大于内存的情况，或者当你希望应用程序的内存占用保持较低时。 #### validate[[datasets.table.InMemoryTable.validate]] ```python validate(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L235) **参数：** full (`bool`，默认为 `False`)：如果为 `True`，则运行开销较大的检查，否则仅运行开销较小的检查。 **引发：** ``pa.lib.ArrowInvalid`` - ``pa.lib.ArrowInvalid`` -- 如果验证失败 执行验证检查。如果验证失败，则会引发异常。 默认情况下仅运行低成本的验证检查。传入 `full=True` 以执行全面的验证检查（可能为 `O(n)`）。 #### equals[[datasets.table.InMemoryTable.equals]] ```python equals(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L251) **参数：** other ([表格](/docs/datasets/v5.2.0/zh/package_reference/table_classes#datasets.table.Table))：用于比较的表格。 check_metadata `bool`，默认为 `False`) : 是否还应检查架构元数据的相等性。 **返回：** `bool` 检查两个表的内容是否相等。 #### to_batches[[datasets.table.InMemoryTable.to_batches]] ```python to_batches(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L268) **参数：** max_chunksize (`int`，默认为 `None`)：`RecordBatch` 块的最大大小。根据各个列的块布局，单个块可能会更小。 **返回：** `List[pyarrow.RecordBatch]` 将 Table 转换为（连续的）`RecordBatch` 对象列表。 #### to_pydict[[datasets.table.InMemoryTable.to_pydict]] ```python to_pydict(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L282) **返回：** `dict` 将 Table 转换为 `dict` 或 `OrderedDict`。 #### to_pandas[[datasets.table.InMemoryTable.to_pandas]] ```python to_pandas(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L300) **参数：** 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 时，会为每一列生成一个内部“块”。虽然这可以暂时减少内存，但请注意，各种 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[[datasets.table.InMemoryTable.to_string]] ```python to_string(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L362) #### field[[datasets.table.InMemoryTable.field]] ```python field(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L381) **参数：** i (`Union[int, str]`) : 要检索的字段索引或名称。 **返回：** `pyarrow.Field` 通过列名或数字索引选择模式字段。 #### 列[[datasets.table.InMemoryTable.column]] ```python column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L394) **参数：** i (`Union[int, str]`) : 要检索的列的索引或名称。 **返回：** `pyarrow.ChunkedArray` 通过列名或数字索引选择列。 #### itercolumns[[datasets.table.InMemoryTable.itercolumns]] ```python itercolumns(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L407) **返回值：** `pyarrow.ChunkedArray` 按数值顺序迭代所有列。 #### schema[[datasets.table.InMemoryTable.schema]] ```python schema() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L416) **返回：** `pyarrow.Schema` 该表及其列的结构。 #### 列[[datasets.table.InMemoryTable.columns]] ```python columns() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L426) **返回：** `List[pa.ChunkedArray]` 按数字顺序排列的所有列的列表。 #### num_columns[[datasets.table.InMemoryTable.num_columns]] ```python num_columns() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L436) **返回：** int 此表格中的列数。 #### num_rows[[datasets.table.InMemoryTable.num_rows]] ```python num_rows() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L446) **返回：** int 此表中的行数。 根据表的定义，所有列的行数都相同。 #### shape[[datasets.table.InMemoryTable.shape]] ```python shape() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L459) **返回：** `(int, int)` 行数和列数。 表格的维度：(#rows, #columns)。 #### nbytes[[datasets.table.InMemoryTable.nbytes]] ```python nbytes() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L469) 表中元素消耗的总字节数。 #### column_names[[datasets.table.InMemoryTable.column_names]] ```python column_names() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L476) 表格列的名称。 #### slice[[datasets.table.InMemoryTable.slice]] ```python slice(offset = 0, length = None) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L859) **参数：** offset (`int`，默认为 `0`)：从表格起始位置到切片的偏移量。 length (`int`，默认为 `None`)：切片长度（默认从偏移量开始直到表格末尾）。 **返回：** `datasets.table.Table` 计算此 Table 的零拷贝切片。 #### filter[[datasets.table.InMemoryTable.filter]] ```python filter(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L876) 从 Table 中筛选记录。有关完整用法，请参阅 `pyarrow.compute.filter`。 #### flatten[[datasets.table.InMemoryTable.flatten]] ```python flatten(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L882) **参数：** memory_pool (`MemoryPool`，默认为 `None`)：用于内存分配，如果不需要，则使用默认内存池。 **返回：** `datasets.table.Table` 展平此表。每个结构体类型的列都会被展平为每个结构体字段对应的一列。其他列保持不变。 #### combine_chunks[[datasets.table.InMemoryTable.combine_chunks]] ```python combine_chunks(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L896) **参数：** memory_pool (`MemoryPool`，默认为 `None`)：用于内存分配，如果不需要，则使用默认内存池。 **返回：** `datasets.table.Table` 通过合并此表中的各个块来创建新表。 每列的 `ChunkedArray` 中所有底层块都会被拼接成零个或一个块。 #### cast[[datasets.table.InMemoryTable.cast]] ```python cast(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L912) **参数：** target_schema (`Schema`)：要转换到的 Schema，字段的名称和顺序必须匹配。 safe (`bool`，默认为 `True`)：检查是否存在溢出或其他不安全的转换。 **返回：** `datasets.table.Table` 将表值转换为另一种模式。 #### replace_schema_metadata[[datasets.table.InMemoryTable.replace_schema_metadata]] ```python replace_schema_metadata(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L927) **参数：** metadata (`dict`，默认为 `None`) -- **返回：** `datasets.table.Table` shallow_copy 实验性功能：通过用指定的新元数据（可以为`None`，这将删除任何现有元数据）替换模式键值元数据，创建表的浅拷贝。 #### add_column[[datasets.table.InMemoryTable.add_column]] ```python add_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L941) **参数：** i (`int`) : 放置该列的索引。 field_ (`Union[str, pyarrow.Field]`) : 如果传入字符串，则类型将从列数据中推断得出。 column (`Union[pyarrow.Array, List[pyarrow.Array]]`) : 列数据。 **返回：** `datasets.table.Table` 添加了传入列的新表。 在指定位置向 Table 添加列。 返回一个添加了该列的新表，原始表对象保持不变。 #### append_column[[datasets.table.InMemoryTable.append_column]] ```python append_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L962) **参数：** field_ (`Union[str, pyarrow.Field]`) : 如果传入字符串，则类型将从列数据中推断得出。 column (`Union[pyarrow.Array, List[pyarrow.Array]]`) : 列数据。 **返回：** `datasets.table.Table` 添加了传入列的新表。 在列的末尾追加列。 #### remove_column[[datasets.table.InMemoryTable.remove_column]] ```python remove_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L979) **参数：** i (`int`) : 要删除的列的索引。 **返回：** `datasets.table.Table` 没有该列的新表格。 创建一个新的 Table，其中移除了指定的列。 #### set_column[[datasets.table.InMemoryTable.set_column]] ```python set_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L993) **参数：** i (`int`) : 放置该列的索引。 field_ (`Union[str, pyarrow.Field]`) : 如果传入字符串，则类型将从列数据中推断得出。 column (`Union[pyarrow.Array, List[pyarrow.Array]]`) : 列数据。 **返回：** `datasets.table.Table` 包含已传递列集的新表。 替换位于指定位置的 Table 中的列。 #### rename_columns[[datasets.table.InMemoryTable.rename_columns]] ```python rename_columns(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1012) 创建新表，并将列重命名为提供的名称。 #### 选择[[datasets.table.InMemoryTable.select]] ```python select(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1035) **参数：** columns (`Union[List[str], List[int]]`) : 要选择的列名或整数索引。 **返回：** [datasets.table.Table](/docs/datasets/v5.2.0/zh/package_reference/table_classes#datasets.table.Table) 包含指定列的新表，并保留元数据。 选择表格的列。 返回一个包含指定列的新表，并保留元数据。 #### drop[[datasets.table.InMemoryTable.drop]] ```python drop(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1018) **参数：** columns (`List[str]`) : 引用现有列的字段名列表。 **返回：** `datasets.table.Table` 没有这些列的新表格。 **引发：** ``KeyError`` - ``KeyError`` -- ：如果传入的列名中有任何一个不存在。 删除一个或多个列并返回一个新表。 #### from_file[[datasets.table.InMemoryTable.from_file]] ```python from_file(filename: str) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L719) #### from_buffer[[datasets.table.InMemoryTable.from_buffer]] ```python from_buffer(buffer: Buffer) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L724) #### from_pandas[[datasets.table.InMemoryTable.from_pandas]] ```python from_pandas(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L729) **参数：** 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 并将其传递给此函数来避免这种行为。 示例： ```python >>> import pandas as pd >>> import pyarrow as pa >>> df = pd.DataFrame({ ... 'int': [1, 2], ... 'str': ['a', 'b'] ... }) >>> pa.Table.from_pandas(df) ``` #### from_arrays[[datasets.table.InMemoryTable.from_arrays]] ```python from_arrays(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L787) **参数：** arrays (`List[Union[pyarrow.Array, pyarrow.ChunkedArray]]`) : 长度相等的数组，应构成该表。 names (`List[str]`, *可选*) : 表格列的名称。如果未传入，则必须传入 schema。 schema (`Schema`，默认为 `None`)：所创建表的 Schema。如果未传入，则必须传入名称。 metadata (`Union[dict, Mapping]`，默认为 `None`)：模式（如果推断得出）的可选元数据。 **返回：** `datasets.table.Table` 从 Arrow 数组构建 Table。 #### from_pydict[[datasets.table.InMemoryTable.from_pydict]] ```python from_pydict(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L807) **参数：** mapping (`Union[dict, Mapping]`) : 从字符串到数组或 Python 列表的映射。 schema (`Schema`，默认为 `None`)：如果未传入，将从 Mapping 值中推断 metadata (`Union[dict, Mapping]`，默认为 `None`)：模式（如果推断得出）的可选元数据。 **返回：** `datasets.table.Table` 从 Arrow 数组或列构建 Table。 #### from_batches[[datasets.table.InMemoryTable.from_batches]] ```python from_batches(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L843) **参数：** batches (`Union[Sequence[pyarrow.RecordBatch], Iterator[pyarrow.RecordBatch]]`) : 要转换的 `RecordBatch` 序列，所有 schema 必须相等。 schema (`Schema`，默认为 `None`)：如果未传入，将从第一个 `RecordBatch` 中推断得出。 **返回：** `datasets.table.Table` 从 `RecordBatches` 序列或迭代器构建 Table。 ## MemoryMappedTable[[datasets.table.MemoryMappedTable]] #### datasets.table.MemoryMappedTable[[datasets.table.MemoryMappedTable]] ```python datasets.table.MemoryMappedTable(table: Table, path: str, replays: typing.Optional[list[tuple[str, tuple, dict]]] = None) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1055) 当表不使用用户的 RAM，而是直接从磁盘加载数据时，我们称该表为内存映射（memory mapped）。 Pickling 操作并不会将数据复制到内存中。相反，它只会序列化内存映射 arrow 文件的路径，以及从磁盘重新加载表时需要“重放”的 transforms 列表。 其实现需要存储应用于底层 pyarrow Table 的所有转换的历史记录，以便在从磁盘重新加载 Table 时能够“重放”这些转换。 这与`InMemoryTable`表不同，后者的 pickle 操作会复制内存中的所有数据。 当数据能够放入内存时，必须使用 `InMemoryTable`；而 `MemoryMapped` 则用于数据大于内存的情况，或者当你希望应用程序的内存占用保持较低时。 #### validate[[datasets.table.MemoryMappedTable.validate]] ```python validate(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L235) **参数：** full (`bool`，默认为 `False`)：如果为 `True`，则运行开销较大的检查，否则仅运行开销较小的检查。 **引发：** ``pa.lib.ArrowInvalid`` - ``pa.lib.ArrowInvalid`` -- 如果验证失败 执行验证检查。如果验证失败，则会引发异常。 默认情况下仅运行低成本的验证检查。传入 `full=True` 以执行全面的验证检查（可能为 `O(n)`）。 #### equals[[datasets.table.MemoryMappedTable.equals]] ```python equals(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L251) **参数：** other ([表格](/docs/datasets/v5.2.0/zh/package_reference/table_classes#datasets.table.Table))：用于比较的表格。 check_metadata `bool`，默认为 `False`) : 是否还应检查架构元数据的相等性。 **返回：** `bool` 检查两个表的内容是否相等。 #### to_batches[[datasets.table.MemoryMappedTable.to_batches]] ```python to_batches(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L268) **参数：** max_chunksize (`int`，默认为 `None`)：`RecordBatch` 块的最大大小。根据各个列的块布局，单个块可能会更小。 **返回：** `List[pyarrow.RecordBatch]` 将 Table 转换为（连续的）`RecordBatch` 对象列表。 #### to_pydict[[datasets.table.MemoryMappedTable.to_pydict]] ```python to_pydict(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L282) **返回：** `dict` 将 Table 转换为 `dict` 或 `OrderedDict`。 #### to_pandas[[datasets.table.MemoryMappedTable.to_pandas]] ```python to_pandas(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L300) **参数：** 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 时，会为每一列生成一个内部“块”。虽然这可以暂时减少内存，但请注意，各种 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[[datasets.table.MemoryMappedTable.to_string]] ```python to_string(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L362) #### field[[datasets.table.MemoryMappedTable.field]] ```python field(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L381) **参数：** i (`Union[int, str]`) : 要检索的字段索引或名称。 **返回：** `pyarrow.Field` 通过列名或数字索引选择模式字段。 #### 列[[datasets.table.MemoryMappedTable.column]] ```python column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L394) **参数：** i (`Union[int, str]`) : 要检索的列的索引或名称。 **返回：** `pyarrow.ChunkedArray` 通过列名或数字索引选择列。 #### itercolumns[[datasets.table.MemoryMappedTable.itercolumns]] ```python itercolumns(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L407) **返回值：** `pyarrow.ChunkedArray` 按数值顺序迭代所有列。 #### schema[[datasets.table.MemoryMappedTable.schema]] ```python schema() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L416) **返回：** `pyarrow.Schema` 该表及其列的结构。 #### 列[[datasets.table.MemoryMappedTable.columns]] ```python columns() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L426) **返回：** `List[pa.ChunkedArray]` 按数字顺序排列的所有列的列表。 #### num_columns[[datasets.table.MemoryMappedTable.num_columns]] ```python num_columns() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L436) **返回：** int 此表格中的列数。 #### num_rows[[datasets.table.MemoryMappedTable.num_rows]] ```python num_rows() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L446) **返回：** int 此表中的行数。 根据表的定义，所有列的行数都相同。 #### shape[[datasets.table.MemoryMappedTable.shape]] ```python shape() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L459) **返回：** `(int, int)` 行数和列数。 表格的维度：(#rows, #columns)。 #### nbytes[[datasets.table.MemoryMappedTable.nbytes]] ```python nbytes() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L469) 表中元素消耗的总字节数。 #### column_names[[datasets.table.MemoryMappedTable.column_names]] ```python column_names() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L476) 表格列的名称。 #### slice[[datasets.table.MemoryMappedTable.slice]] ```python slice(offset = 0, length = None) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1114) **参数：** offset (`int`，默认为 `0`)：从表格起始位置到切片的偏移量。 length (`int`，默认为 `None`)：切片长度（默认从偏移量开始直到表格末尾）。 **返回：** `datasets.table.Table` 计算此 Table 的零拷贝切片。 #### filter[[datasets.table.MemoryMappedTable.filter]] ```python filter(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1133) 从 Table 中筛选记录。有关完整用法，请参阅 `pyarrow.compute.filter`。 #### flatten[[datasets.table.MemoryMappedTable.flatten]] ```python flatten(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1141) **参数：** memory_pool (`MemoryPool`，默认为 `None`)：用于内存分配，如果不需要，则使用默认内存池。 **返回：** `datasets.table.Table` 展平此表。每个结构体类型的列都会被展平为每个结构体字段对应的一列。其他列保持不变。 #### combine_chunks[[datasets.table.MemoryMappedTable.combine_chunks]] ```python combine_chunks(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1157) **参数：** memory_pool (`MemoryPool`，默认为 `None`)：用于内存分配，如果不需要，则使用默认内存池。 **返回：** `datasets.table.Table` 通过合并此表中的各个块来创建新表。 每列的 ChunkedArray 中所有底层块都被拼接为零个或一个块。 #### cast[[datasets.table.MemoryMappedTable.cast]] ```python cast(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1175) **参数：** target_schema (`Schema`)：要转换到的 Schema，字段的名称和顺序必须匹配。 safe (`bool`，默认为 `True`)：检查是否存在溢出或其他不安全的转换。 **返回：** `datasets.table.Table` 将表值转换为另一种模式 #### replace_schema_metadata[[datasets.table.MemoryMappedTable.replace_schema_metadata]] ```python replace_schema_metadata(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1192) **参数：** metadata (`dict`，默认为 `None`) -- **返回：** `datasets.table.Table` shallow_copy 实验性功能：通过用指定的新元数据（可以为 None，这会删除任何现有元数据）替换 schema 键值元数据，创建表的浅拷贝。 #### add_column[[datasets.table.MemoryMappedTable.add_column]] ```python add_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1208) **参数：** i (`int`) : 放置该列的索引。 field_ (`Union[str, pyarrow.Field]`) : 如果传入字符串，则类型将从列数据中推断得出。 column (`Union[pyarrow.Array, List[pyarrow.Array]]`) : 列数据。 **返回：** `datasets.table.Table` 添加了传入列的新表。 在指定位置向 Table 添加列。 返回一个添加了该列的新表，原始表对象保持不变。 #### append_column[[datasets.table.MemoryMappedTable.append_column]] ```python append_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1231) **参数：** field_ (`Union[str, pyarrow.Field]`) : 如果传入字符串，则类型将从列数据中推断得出。 column (`Union[pyarrow.Array, List[pyarrow.Array]]`) : 列数据。 **返回：** `datasets.table.Table` 添加了传入列的新表。 在列的末尾追加列。 #### remove_column[[datasets.table.MemoryMappedTable.remove_column]] ```python remove_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1250) **参数：** i (`int`) : 要删除的列的索引。 **返回：** `datasets.table.Table` 没有该列的新表格。 创建一个新的 Table，其中移除了指定的列。 #### set_column[[datasets.table.MemoryMappedTable.set_column]] ```python set_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1266) **参数：** i (`int`) : 放置该列的索引。 field_ (`Union[str, pyarrow.Field]`) : 如果传入字符串，则类型将从列数据中推断得出。 column (`Union[pyarrow.Array, List[pyarrow.Array]]`) : 列数据。 **返回：** `datasets.table.Table` 包含已传递列集的新表。 替换位于指定位置的 Table 中的列。 #### rename_columns[[datasets.table.MemoryMappedTable.rename_columns]] ```python rename_columns(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1287) 创建新表，并将列重命名为提供的名称。 #### 选择[[datasets.table.MemoryMappedTable.select]] ```python select(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1314) **参数：** columns (`Union[List[str], List[int]]`) : 要选择的列名或整数索引。 **返回：** [datasets.table.Table](/docs/datasets/v5.2.0/zh/package_reference/table_classes#datasets.table.Table) 包含指定列的新表，并保留元数据。 选择表格的列。 返回一个包含指定列的新表，并保留元数据。 #### drop[[datasets.table.MemoryMappedTable.drop]] ```python drop(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1295) **参数：** columns (`List[str]`) : 引用现有列的字段名列表。 **返回：** `datasets.table.Table` 没有这些列的新表格。 **引发：** ``KeyError`` - ``KeyError`` -- ：如果传入的列名中有任何一个不存在。 删除一个或多个列并返回一个新表。 #### from_file[[datasets.table.MemoryMappedTable.from_file]] ```python from_file(filename: str, replays = None) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1081) ## ConcatenationTable[[datasets.table.ConcatenationTable]] #### datasets.table.ConcatenationTable[[datasets.table.ConcatenationTable]] ```python datasets.table.ConcatenationTable(table: Table, blocks: list) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1339) 该表由多个称为块的表拼接而成。它支持沿轴 0（追加行）和轴 1（追加列）进行拼接。 底层的表被称为“块”，可以是 `InMemoryTable` 或 `MemoryMappedTable` 对象。这使得可以组合来自内存或内存映射的表。当 `ConcatenationTable` 被 pickle 时，每个块都会被 pickle： - `InMemoryTable` 对象通过复制内存中的所有数据进行 pickle 序列化。 - MemoryMappedTable 对象在序列化时不会将数据复制到内存中。 相反，仅对内存映射的 arrow 文件的路径以及从磁盘重新加载表时用于“重放”的转换列表进行 pickle 序列化。 其实现要求单独存储每个块。`blocks` 属性存储一个块列表的列表。第一个轴沿轴 0 拼接表格（即追加行），第二个轴沿轴 1 拼接表格（即追加列）。 在沿 axis 0 进行拼接时，如果某些列缺失，则用 null 值填充。此操作通过 `pyarrow.concat_tables(tables, promote=True)` 实现。 您可以通过访问 `ConcatenationTable.table` 属性来访问完全合并后的表格，并通过访问 `ConcatenationTable.blocks` 属性来访问各个块。 #### validate[[datasets.table.ConcatenationTable.validate]] ```python validate(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L235) **参数：** full (`bool`，默认为 `False`)：如果为 `True`，则运行开销较大的检查，否则仅运行开销较小的检查。 **引发：** ``pa.lib.ArrowInvalid`` - ``pa.lib.ArrowInvalid`` -- 如果验证失败 执行验证检查。如果验证失败，则会引发异常。 默认情况下仅运行低成本的验证检查。传入 `full=True` 以执行全面的验证检查（可能为 `O(n)`）。 #### equals[[datasets.table.ConcatenationTable.equals]] ```python equals(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L251) **参数：** other ([表格](/docs/datasets/v5.2.0/zh/package_reference/table_classes#datasets.table.Table))：用于比较的表格。 check_metadata `bool`，默认为 `False`) : 是否还应检查架构元数据的相等性。 **返回：** `bool` 检查两个表的内容是否相等。 #### to_batches[[datasets.table.ConcatenationTable.to_batches]] ```python to_batches(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L268) **参数：** max_chunksize (`int`，默认为 `None`)：`RecordBatch` 块的最大大小。根据各个列的块布局，单个块可能会更小。 **返回：** `List[pyarrow.RecordBatch]` 将 Table 转换为（连续的）`RecordBatch` 对象列表。 #### to_pydict[[datasets.table.ConcatenationTable.to_pydict]] ```python to_pydict(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L282) **返回：** `dict` 将 Table 转换为 `dict` 或 `OrderedDict`。 #### to_pandas[[datasets.table.ConcatenationTable.to_pandas]] ```python to_pandas(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L300) **参数：** 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 时，会为每一列生成一个内部“块”。虽然这可以暂时减少内存，但请注意，各种 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[[datasets.table.ConcatenationTable.to_string]] ```python to_string(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L362) #### field[[datasets.table.ConcatenationTable.field]] ```python field(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L381) **参数：** i (`Union[int, str]`) : 要检索的字段索引或名称。 **返回：** `pyarrow.Field` 通过列名或数字索引选择模式字段。 #### 列[[datasets.table.ConcatenationTable.column]] ```python column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L394) **参数：** i (`Union[int, str]`) : 要检索的列的索引或名称。 **返回：** `pyarrow.ChunkedArray` 通过列名或数字索引选择列。 #### itercolumns[[datasets.table.ConcatenationTable.itercolumns]] ```python itercolumns(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L407) **返回值：** `pyarrow.ChunkedArray` 按数值顺序迭代所有列。 #### schema[[datasets.table.ConcatenationTable.schema]] ```python schema() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L416) **返回：** `pyarrow.Schema` 该表及其列的结构。 #### 列[[datasets.table.ConcatenationTable.columns]] ```python columns() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L426) **返回：** `List[pa.ChunkedArray]` 按数字顺序排列的所有列的列表。 #### num_columns[[datasets.table.ConcatenationTable.num_columns]] ```python num_columns() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L436) **返回：** int 此表格中的列数。 #### num_rows[[datasets.table.ConcatenationTable.num_rows]] ```python num_rows() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L446) **返回：** int 此表中的行数。 根据表的定义，所有列的行数都相同。 #### shape[[datasets.table.ConcatenationTable.shape]] ```python shape() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L459) **返回：** `(int, int)` 行数和列数。 表格的维度：(#rows, #columns)。 #### nbytes[[datasets.table.ConcatenationTable.nbytes]] ```python nbytes() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L469) 表中元素消耗的总字节数。 #### column_names[[datasets.table.ConcatenationTable.column_names]] ```python column_names() ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L476) 表格列的名称。 #### slice[[datasets.table.ConcatenationTable.slice]] ```python slice(offset = 0, length = None) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1548) **参数：** offset (`int`，默认为 `0`)：从表格起始位置到切片的偏移量。 length (`int`，默认为 `None`)：切片长度（默认从偏移量开始直到表格末尾）。 **返回：** `datasets.table.Table` 计算此 Table 的零拷贝切片。 #### filter[[datasets.table.ConcatenationTable.filter]] ```python filter(mask, *args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1579) 从 Table 中筛选记录。有关完整用法，请参阅 `pyarrow.compute.filter`。 #### flatten[[datasets.table.ConcatenationTable.flatten]] ```python flatten(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1590) **参数：** memory_pool (`MemoryPool`，默认为 `None`)：用于内存分配，如果不需要，则使用默认内存池。 **返回：** `datasets.table.Table` 展平此表。每个结构体类型的列都会被展平为每个结构体字段对应的一列。其他列保持不变。 #### combine_chunks[[datasets.table.ConcatenationTable.combine_chunks]] ```python combine_chunks(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1608) **参数：** memory_pool (`MemoryPool`，默认为 `None`)：用于内存分配，如果不需要，则使用默认内存池。 **返回：** `datasets.table.Table` 通过合并此表中的各个块来创建新表。 每列的 `ChunkedArray` 中所有底层块都会被拼接成零个或一个块。 #### cast[[datasets.table.ConcatenationTable.cast]] ```python cast(target_schema, *args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1628) **参数：** target_schema (`Schema`)：要转换到的 Schema，字段的名称和顺序必须匹配。 safe (`bool`，默认为 `True`)：检查是否存在溢出或其他不安全的转换。 **返回：** `datasets.table.Table` 将表值转换为另一种模式。 #### replace_schema_metadata[[datasets.table.ConcatenationTable.replace_schema_metadata]] ```python replace_schema_metadata(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1659) **参数：** metadata (`dict`，默认为 `None`) -- **返回：** `datasets.table.Table` shallow_copy 实验性功能：通过用指定的新元数据（可以为`None`，这将删除任何现有元数据）替换模式键值元数据，创建表的浅拷贝。 #### add_column[[datasets.table.ConcatenationTable.add_column]] ```python add_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1677) **参数：** i (`int`) : 放置该列的索引。 field_ (`Union[str, pyarrow.Field]`) : 如果传入字符串，则类型将从列数据中推断得出。 column (`Union[pyarrow.Array, List[pyarrow.Array]]`) : 列数据。 **返回：** `datasets.table.Table` 添加了传入列的新表。 在指定位置向 Table 添加列。 返回一个添加了该列的新表，原始表对象保持不变。 #### append_column[[datasets.table.ConcatenationTable.append_column]] ```python append_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1698) **参数：** field_ (`Union[str, pyarrow.Field]`) : 如果传入字符串，则类型将从列数据中推断得出。 column (`Union[pyarrow.Array, List[pyarrow.Array]]`) : 列数据。 **返回：** `datasets.table.Table` 添加了传入列的新表。 在列的末尾追加列。 #### remove_column[[datasets.table.ConcatenationTable.remove_column]] ```python remove_column(i, *args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1715) **参数：** i (`int`) : 要删除的列的索引。 **返回：** `datasets.table.Table` 没有该列的新表格。 创建一个新的 Table，其中移除了指定的列。 #### set_column[[datasets.table.ConcatenationTable.set_column]] ```python set_column(*args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1739) **参数：** i (`int`) : 放置该列的索引。 field_ (`Union[str, pyarrow.Field]`) : 如果传入字符串，则类型将从列数据中推断得出。 column (`Union[pyarrow.Array, List[pyarrow.Array]]`) : 列数据。 **返回：** `datasets.table.Table` 包含已传递列集的新表。 替换位于指定位置的 Table 中的列。 #### rename_columns[[datasets.table.ConcatenationTable.rename_columns]] ```python rename_columns(names, *args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1758) 创建新表，并将列重命名为提供的名称。 #### 选择[[datasets.table.ConcatenationTable.select]] ```python select(columns, *args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1792) **参数：** columns (`Union[List[str], List[int]]`) : 要选择的列名或整数索引。 **返回：** [datasets.table.Table](/docs/datasets/v5.2.0/zh/package_reference/table_classes#datasets.table.Table) 包含指定列的新表，并保留元数据。 选择表格的列。 返回一个包含指定列的新表，并保留元数据。 #### drop[[datasets.table.ConcatenationTable.drop]] ```python drop(columns, *args, **kwargs) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1771) **参数：** columns (`List[str]`) : 引用现有列的字段名列表。 **返回：** `datasets.table.Table` 没有这些列的新表格。 **引发：** ``KeyError`` - ``KeyError`` -- ：如果传入的列名中有任何一个不存在。 删除一个或多个列并返回一个新表。 #### from_blocks[[datasets.table.ConcatenationTable.from_blocks]] ```python from_blocks(blocks: ~TableBlockContainer) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1444) #### from_tables[[datasets.table.ConcatenationTable.from_tables]] ```python from_tables(tables: list, axis: int = 0) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1458) **参数：** tables （`Table` 列表或 `pyarrow.Table` 列表）：表格列表。 axis (`{0, 1}`，默认为 `0`，表示沿行方向)：要拼接的轴，其中 `0` 表示沿行方向（垂直）拼接，`1` 表示沿列方向（水平）拼接。 从表列表创建 `ConcatenationTable`。 ## 工具[[datasets.table.concat_tables]] #### datasets.table.concat_tables[[datasets.table.concat_tables]] ```python datasets.table.concat_tables(tables: list, axis: int = 0) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1812) **参数：** tables （`Table` 列表）：要拼接的表格列表。 axis (`{0, 1}`，默认为 `0`，表示沿行方向)：要拼接的轴，其中 `0` 表示沿行方向（垂直）拼接，`1` 表示沿列方向（水平）拼接。 **返回：** `datasets.table.Table` 如果输入表的数量 > 1，则返回的表是一个 `datasets.table.ConcatenationTable`。否则，如果只有一个表，则按原样返回。 拼接表格。 #### datasets.table.list_table_cache_files[[datasets.table.list_table_cache_files]] ```python datasets.table.list_table_cache_files(table: Table) ``` [源代码](https://github.com/huggingface/datasets/blob/5.2.0/src/datasets/table.py#L1835) **返回：** `List[str]` 由该表格加载的缓存文件路径列表。 获取由表加载的缓存文件。当表的部分数据通过内存映射从磁盘读取时，会使用缓存文件。