資料集文件

表格類別

資料集 (Datasets)

加入 Hugging Face 社群

並獲得增強的文件體驗

在模型、資料集和 Spaces 上進行協作

透過加速推論實現更快的範例

切換文件主題

開始使用

表格類別 (Table Classes)

每個 Dataset 物件皆由 PyArrow Table 作為後端支援。表格可以從磁碟載入（記憶體映射）或直接載入至記憶體中。目前提供多種表格類型，它們皆繼承自 table.Table。

Table

class datasets.table.Table

( table: Table )

透過組合 (composition) 包裝 pyarrow Table。這是 InMemoryTable、MemoryMappedTable 和 ConcatenationTable 的基底類別。

它實作了 pyarrow 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) — 是否同時檢查 schema 中繼資料的一致性。

返回

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) — 將含有空值 (nulls) 的整數轉換為物件 (objects)。
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，則在重建 DataFrame 索引時不使用「pandas」中繼資料（若有的話）。
safe (bool, 預設為 True) — 對於某些資料類型，為了將資料儲存在 pandas DataFrame 或 Series 中，需要進行型別轉換（例如 pandas 中的時間戳記始終以奈秒為單位儲存）。此選項控制是否進行安全的轉換。
split_blocks (bool, 預設為 False) — 若設為 True，則從 RecordBatch 或 Table 建立 pandas.DataFrame 時，為每個欄位產生一個內部「區塊」。雖然這可以暫時減少記憶體使用，但請注意，各種 pandas 操作可能會觸發「合併」(consolidation)，這可能會導致記憶體用量大幅增加。
self_destruct (bool, 預設為 False) — 實驗性功能：若設為 True，在將 Arrow 物件轉換為 pandas 時會嘗試解除配置原始的 Arrow 記憶體。若您在呼叫此選項的 to_pandas 後仍使用該物件，程式將會崩潰。
types_mapper (function, 預設為 None) — 一個將 pyarrow 資料類型映射到 pandas ExtensionDtype 的函式。這可以用於覆蓋內建 pyarrow 類型的預設轉換，或是在 Table schema 中缺少 pandas_metadata 時使用。該函式接收一個 pyarrow 資料類型，並應回傳一個 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]) — 要檢索的欄位索引或名稱。

依據欄位名稱或數值索引來選取 schema 欄位。

column

( *args **kwargs )

參數

i (Union[int, str]) — 要檢索的欄位索引或名稱。

依據欄位名稱或數值索引來選取欄位。

itercolumns

( *args **kwargs )

依數值順序迭代所有欄位。

schema

( )

表格及其欄位的 Schema。

columns

( )

按數值順序排列的所有欄位列表。

num_columns

( )

此表格中的欄位數量。

num_rows

( )

此表格中的列數。

根據表格定義，所有欄位皆具有相同的列數。

shape

( ) → (int, int)

返回

(int, int)

列數與欄位數。

表格維度：(#列, #欄)。

nbytes

( )

表格元素所佔用的總位元組數。

InMemoryTable

class datasets.table.InMemoryTable

( table: Table )

當表格載入到使用者的 RAM 中時，稱為記憶體內表格 (in-memory)。

對其進行序列化 (pickling) 會使用記憶體複製所有資料。其實作方式簡單，直接使用底層的 pyarrow Table 方法。

這與 MemoryMapped 表格不同，對於 MemoryMapped，序列化時不會將所有資料複製到記憶體中。對於 MemoryMapped，反序列化時會從磁碟重新載入表格。

當資料適合放入記憶體時，必須使用 InMemoryTable；而當資料大於記憶體容量，或是您希望應用程式的記憶體使用量保持在低水位時，則建議使用 MemoryMapped。

validate

( *args **kwargs )

參數

full (bool, 預設為 False) — 若設為 True，則執行耗時較長的完整檢查；否則僅執行快速檢查。

引發

pa.lib.ArrowInvalid

pa.lib.ArrowInvalid — 若驗證失敗則拋出此錯誤。

執行驗證檢查。若驗證失敗，將會引發例外。

預設僅執行快速驗證檢查。若需要徹底驗證，請傳入 full=True（可能為 O(n) 複雜度）。

equals

( *args **kwargs ) → bool

參數

other (Table) — 用來進行比較的表格。
check_metadata (bool, 預設為 False) — 是否同時檢查 schema 中繼資料的一致性。

返回

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) — 將含有空值 (nulls) 的整數轉換為 object 型別。
date_as_object (bool，預設為 True) — 將日期轉換為 object 型別。若為 False，則轉換為 datetime64[ns] 資料型別 (dtype)。
timestamp_as_object (bool，預設為 False) — 將非奈秒級的時間戳記 (np.datetime64) 轉換為 object 型別。若您的時間戳記超出標準奈秒時間範圍（西元 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 時，為每一欄產生一個內部的「區塊」(block)。雖然這可以暫時減少記憶體使用量，但請注意，各種 pandas 操作可能會觸發「合併」(consolidation)，這可能會導致記憶體用量大幅膨脹。
self_destruct (bool，預設為 False) — 實驗性功能：若為 True，則在將 Arrow 物件轉換為 pandas 時，嘗試釋放原始的 Arrow 記憶體。若您在以此選項呼叫 to_pandas 之後使用該物件，將會導致程式崩潰。
types_mapper (function，預設為 None) — 一個將 pyarrow 資料型別對應到 pandas ExtensionDtype 的函式。此函式可用於覆寫預設的 pandas 型別轉換，或在 Table schema 中缺少 pandas_metadata 時使用。該函式接收一個 pyarrow 資料型別，並預期回傳一個 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]) — 要擷取的欄位索引或名稱。

依據欄位名稱或數值索引來選取 schema 欄位。

column

( *args **kwargs )

參數

i (Union[int, str]) — 要擷取的欄索引或名稱。

依據欄位名稱或數值索引來選取欄位。

itercolumns

( *args **kwargs )

依數值順序迭代所有欄位。

schema

( )

表格及其欄位的 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) — 切片的長度（預設為從偏移量開始到表格結束）。

計算此表格的零複製 (zero-copy) 切片。

filter (篩選器)

( *args **kwargs )

從表格中選取記錄。完整用法請參閱 pyarrow.compute.filter。

flatten

( *args **kwargs )

參數

memory_pool (MemoryPool，預設為 None) — 若有需要，用於記憶體配置；否則使用預設池。

扁平化此表格。每個具有結構型別 (struct type) 的欄位會被扁平化，轉換為每個結構欄位對應一欄。其他欄位保持不變。

combine_chunks

( *args **kwargs )

參數

memory_pool (MemoryPool，預設為 None) — 若有需要，用於記憶體配置；否則使用預設池。

透過合併此表格現有的區塊 (chunks) 來建立一個新表格。

每個欄位的 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，這會刪除任何現有的元數據）來建立表格的淺拷貝。

add_column

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

參數

i (int) — 放置欄位的索引。
field_ (Union[str, pyarrow.Field]) — 若傳入字串，型別將從欄位資料中推斷。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 欄位資料。

返回

datasets.table.Table

包含已新增欄位的新表格。

在表格的指定位置新增欄位。

回傳一個新增了該欄位的新表格，原始表格物件保持不變。

append_column

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

參數

field_ (Union[str, pyarrow.Field]) — 若傳入字串，型別將從欄位資料中推斷。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 欄位資料。

返回

datasets.table.Table

包含已新增欄位的新表格。

在欄位列表末尾附加欄位。

remove_column

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

參數

i (int) — 要移除的欄位索引。

返回

datasets.table.Table

不含該欄位的新表格。

建立一個移除了指定欄位的新表格。

set_column

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

參數

i (int) — 放置欄位的索引。
field_ (Union[str, pyarrow.Field]) — 若傳入字串，型別將從欄位資料中推斷。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 欄位資料。

返回

datasets.table.Table

包含已設定欄位的新表格。

取代表格中指定位置的欄位。

rename_columns

( *args **kwargs )

建立一個將欄位重新命名為所提供名稱的新表格。

select

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

參數

columns (Union[List[str], List[int]]) — 要選取的欄位名稱或整數索引。

返回

datasets.table.Table

包含指定欄位且保留了元數據的新表格。

選取表格的欄位。

回傳一個包含指定欄位且保留了元數據的新表格。

drop

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

參數

columns (List[str]) — 參照現有欄位的欄位名稱列表。

返回

datasets.table.Table

不含這些欄位的新表格。

引發

KeyError

KeyError — ：若傳入的任何欄位名稱不存在，則引發此錯誤。

刪除一或多個欄位並回傳新表格。

from_file

( filename: str )

from_buffer

( buffer: Buffer )

from_pandas

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

參數

df (pandas.DataFrame) —
schema (pyarrow.Schema, 選填) — Arrow Table 的預期結構 (Schema)。若無法自動推斷欄位型別，可用此參數指定。若傳入此參數，輸出將完全符合該結構。若 Schema 指定的欄位未在 DataFrame 的欄位或索引中找到，將會引發錯誤。DataFrame 中未在 Schema 指定的額外欄位或索引層級將會被忽略。
preserve_index (bool, 選填) — 是否將索引儲存為結果 Table 中的額外欄位。預設為 None，會將索引儲存為欄位，但 RangeIndex 除外（僅作為 metadata 儲存）。使用 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 的 dtype 進行推斷。對於非 object 型態的 Series，NumPy 的 dtype 會轉換為對應的 Arrow 型別。對於 object 型態，我們需要透過查看該 Series 中的 Python 物件來猜測其資料型別。

請注意，object dtype 的 Series 並不總是包含足夠的資訊來推斷出具有明確意義的 Arrow 型別。如果我們無法推斷型別（例如 DataFrame 長度為 0，或 Series 僅包含 None/nan 物件），型別將被設為 null。您可以透過明確建構一個 schema 並將其傳遞給此函數來避免這種情況。

範例

>>> import pandas as pd
>>> import pyarrow as pa
>>> df = pd.DataFrame({
    ...     'int': [1, 2],
    ...     'str': ['a', 'b']
    ... })
>>> pa.Table.from_pandas(df)
<pyarrow.lib.Table object at 0x7f05d1fb1b40>

from_arrays

( *args **kwargs )

參數

arrays (List[Union[pyarrow.Array, pyarrow.ChunkedArray]]) — 組成表格的等長陣列。
names (List[str], 選填) — 表格欄位的名稱。若未傳入此參數，則必須傳入 schema。
schema (Schema，預設為 None) — 建立表格所用的 schema。若未傳入此參數，則必須傳入 names。
metadata (Union[dict, Mapping]，預設為 None) — schema 的選擇性中繼資料 (若有推斷)。

從 Arrow 陣列建構 Table。

from_pydict

( *args **kwargs )

參數

mapping (Union[dict, Mapping]) — 字串到 Arrays 或 Python 清單的對應關係。
schema (Schema，預設為 None) — 若未傳入此參數，則將從 Mapping 的值中進行推斷。
metadata (Union[dict, Mapping]，預設為 None) — schema 的選擇性中繼資料 (若有推斷)。

從 Arrow 陣列或欄位建構 Table。

from_batches

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

參數

batches (Union[Sequence[pyarrow.RecordBatch], Iterator[pyarrow.RecordBatch]]) — 要轉換的 RecordBatch 序列，所有 schema 必須相同。
schema (Schema，預設為 None) — 若未傳入此參數，將從第一個 RecordBatch 中進行推斷。

返回

datasets.table.Table

從 Arrow RecordBatches 的序列或迭代器建構 Table。

MemoryMappedTable

class datasets.table.MemoryMappedTable

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

當表格不使用使用者記憶體 (RAM)，而是直接從磁碟讀取資料時，稱為記憶體映射 (memory mapped) 表格。

對其進行序列化 (pickling) 時不會將資料複製到記憶體中。相反地，只會序列化指向記憶體映射 arrow 檔案的路徑，以及從磁碟重新載入表格時需要「重播」的轉換操作清單。

其實作需要儲存所有應用於底層 pyarrow Table 的轉換歷史記錄，以便在從磁碟重新載入 Table 時可以進行「重播」。

這與 InMemoryTable 不同，後者在序列化時會將所有資料複製到記憶體中。

當資料適合放入記憶體時，必須使用 InMemoryTable；而當資料大於記憶體容量，或是您希望應用程式的記憶體使用量保持在低水位時，則建議使用 MemoryMapped。

validate

( *args **kwargs )

參數

full (bool，預設為 False) — 若為 True，則執行耗時的檢查，否則僅執行較輕量的檢查。

引發

pa.lib.ArrowInvalid

pa.lib.ArrowInvalid — 若驗證失敗則拋出此錯誤。

執行驗證檢查。若驗證失敗，將會引發例外。

預設僅執行快速驗證檢查。若需要徹底驗證，請傳入 full=True（可能為 O(n) 複雜度）。

equals

( *args **kwargs ) → bool

參數

other (Table) — 用於比較的表格。
check_metadata (bool，預設為 False) — 是否同時檢查 schema 的中繼資料是否相等。

返回

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 的整數轉換為 object 型態。
date_as_object (bool，預設為 True) — 將日期轉換為 object 型態。若為 False，則轉換為 datetime64[ns] dtype。
timestamp_as_object (bool，預設為 False) — 將非奈秒級時間戳記 (np.datetime64) 轉換為 object 型態。若您擁有的時間戳記超出奈秒級時間戳記的正常日期範圍 (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 操作可能會觸發「合併」(consolidation)，這可能會導致記憶體使用量激增。
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]) — 要檢索的欄位索引或名稱。

依據欄位名稱或數值索引來選取 schema 欄位。

column

( *args **kwargs )

參數

i (Union[int, str]) — 要檢索的欄位索引或名稱。

依據欄位名稱或數值索引來選取欄位。

itercolumns

( *args **kwargs )

依數值順序迭代所有欄位。

schema

( )

表格及其欄位的 Schema。

columns

( )

按數值順序排列的所有欄位列表。

num_columns

( )

此表格中的欄位數量。

num_rows

( )

此表格中的列數。

根據表格定義，所有欄位皆具有相同的列數。

shape

( ) → (int, int)

返回

(int, int)

列數與欄位數。

表格維度：(#列, #欄)。

nbytes

( )

表格元素所佔用的總位元組數。

column_names

( )

表格欄位的名稱。

slice

( offset = 0 length = None )

參數

offset (int，預設為 0) — 從表格開始處進行切片 (slice) 的位移量。
length (int，預設為 None) — 切片的長度（預設為從偏移量開始直到表格結尾）。

計算此表格的零複製 (zero-copy) 切片。

filter (篩選器)

( *args **kwargs )

從表格中選取記錄。完整用法請參閱 pyarrow.compute.filter。

flatten

( *args **kwargs )

參數

memory_pool (MemoryPool，預設為 None) — 用於記憶體配置（如有需要），否則使用預設集區。

扁平化此表格。每個具有結構型別 (struct type) 的欄位會被扁平化，轉換為每個結構欄位對應一欄。其他欄位保持不變。

combine_chunks

( *args **kwargs )

參數

memory_pool (MemoryPool，預設為 None) — 用於記憶體配置（如有需要），否則使用預設集區。

透過合併此表格現有的區塊 (chunks) 來建立一個新表格。

每一欄 ChunkedArray 中的所有底層區塊（chunks）都會合併為一個或零個區塊。

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

實驗性質：透過以指定的新詮釋資料（metadata）取代架構的鍵值詮釋資料，來建立表格的淺層複製（若為 None，則會刪除任何現有的詮釋資料）。

add_column

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

參數

i (int) — 放置該欄位的索引。
field_ (Union[str, pyarrow.Field]) — 若傳入字串，則型別會從欄位資料中推導出來。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 欄位資料。

返回

datasets.table.Table

包含已新增欄位的新表格。

在表格的指定位置新增欄位。

回傳一個新增了該欄位的新表格，原始表格物件保持不變。

append_column

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

參數

field_ (Union[str, pyarrow.Field]) — 若傳入字串，則型別會從欄位資料中推導出來。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 欄位資料。

返回

datasets.table.Table

包含已新增欄位的新表格。

在欄位列表末尾附加欄位。

remove_column

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

參數

i (int) — 要移除的欄位索引。

返回

datasets.table.Table

不含該欄位的新表格。

建立一個移除了指定欄位的新表格。

set_column

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

參數

i (int) — 放置該欄位的索引。
field_ (Union[str, pyarrow.Field]) — 若傳入字串，則型別會從欄位資料中推導出來。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 欄位資料。

返回

datasets.table.Table

包含已設定欄位的新表格。

取代表格中指定位置的欄位。

rename_columns

( *args **kwargs )

建立一個將欄位重新命名為所提供名稱的新表格。

select

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

參數

columns (Union[List[str], List[int]]) — 要選取的欄位名稱或整數索引。

返回

datasets.table.Table

包含指定欄位且保留了元數據的新表格。

選取表格的欄位。

回傳一個包含指定欄位且保留了元數據的新表格。

drop

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

參數

columns (List[str]) — 參照現有欄位的欄位名稱列表。

返回

datasets.table.Table

不含這些欄位的新表格。

引發

KeyError

KeyError — ：若傳入的任何欄位名稱不存在，則引發此錯誤。

刪除一或多個欄位並回傳新表格。

from_file

( filename: str replays = None )

ConcatenationTable

class datasets.table.ConcatenationTable

( table: Table blocks: list )

此表格源自多個被稱為「區塊（blocks）」的表格之串接。它支援在軸 0（附加列）和軸 1（附加欄）上進行串接。

底層的表格被稱為「區塊」，可以是 InMemoryTable 或 MemoryMappedTable 物件。這允許組合來自記憶體或記憶體對映（memory mapped）的表格。當 ConcatenationTable 被 pickle（序列化）時，每個區塊都會被 pickle。

InMemoryTable 物件透過將所有資料複製到記憶體中來進行 pickle。
MemoryMappedTable 物件則在不將資料複製到記憶體的情況下進行 pickle。取而代之的是，僅儲存記憶體對映 arrow 檔案的路徑，以及當從磁碟重新載入表格時需要「重播（replays）」的轉換列表。

其實現需要分別儲存每個區塊。blocks 屬性儲存了一個區塊列表的列表。第一個軸將表格沿著軸 0 進行串接（附加列），而第二個軸則沿著軸 1 進行串接（附加欄）。

如果在軸 0 上進行串接時缺少某些欄位，它們會以 null 值填補。這是透過 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) — 是否同時檢查架構詮釋資料（schema metadata）是否相等。

返回

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 年至 2262 年），這將非常有用。若為 False，所有時間戳記都會轉換為 datetime64[ns] dtype。
use_threads (bool，預設為 True) — 是否使用多執行緒進行平行轉換。
deduplicate_objects (bool，預設為 False) — 建立時不建立多個 Python 物件副本，以節省記憶體使用。轉換速度會較慢。
ignore_metadata (bool，預設為 False) — 若為 True，則不使用「pandas」詮釋資料來重建 DataFrame 索引（如果存在的話）。
safe (bool，預設為 True) — 對於某些資料型別，需要進行轉換才能將資料儲存在 pandas DataFrame 或 Series 中（例如，時間戳記在 pandas 中總是以奈秒儲存）。此選項控制轉換是否為安全轉換。
split_blocks (bool，預設為 False) — 若為 True，在從 RecordBatch 或 Table 建立 pandas.DataFrame 時，為每一欄產生一個內部「區塊」。雖然這可以暫時減少記憶體使用，但請注意，各種 pandas 操作可能會觸發「合併（consolidation）」，這可能會導致記憶體使用量激增。
self_destruct (bool，預設為 False) — 實驗性質：若為 True，在將 Arrow 物件轉換為 pandas 時，嘗試取消配置原始的 Arrow 記憶體。如果您在呼叫帶有此選項的 to_pandas 後使用該物件，將會導致您的程式崩潰。
types_mapper (function，預設為 None) — 將 pyarrow DataType 對應至 pandas ExtensionDtype 的函式。這可用於覆寫內建 pyarrow 型別轉換的預設 pandas 型別，或在表格 Schema 中缺少 pandas_metadata 時使用。該函式會接收一個 pyarrow DataType，並預期傳回一個 pandas ExtensionDtype，若該型別應使用預設轉換，則傳回 None。如果您有一個映射字典，可以傳入 dict.get 作為函式。

返回

pandas.Series 或 pandas.DataFrame

根據物件類型，為 pandas.Series 或 pandas.DataFrame

視情況轉換為與 pandas 相容的 NumPy 陣列或 DataFrame。

to_string

( *args **kwargs )

field

( *args **kwargs )

參數

i (Union[int, str]) — 要擷取的欄位索引或名稱。

依據欄位名稱或數值索引來選取 schema 欄位。

column

( *args **kwargs )

參數

i (Union[int, str]) — 要擷取的欄位索引或名稱。

依據欄位名稱或數值索引來選取欄位。

itercolumns

( *args **kwargs )

依數值順序迭代所有欄位。

schema

( )

表格及其欄位的 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) — 切片長度（預設從偏移量開始直到表格末尾）。

計算此表格的零複製 (zero-copy) 切片。

filter (篩選器)

( mask *args **kwargs )

從表格中選取記錄。完整用法請參閱 pyarrow.compute.filter。

flatten

( *args **kwargs )

參數

memory_pool (MemoryPool，預設值為 None) — 用於記憶體分配（若有需要），否則使用預設記憶體池。

扁平化此表格。每個具有結構型別 (struct type) 的欄位會被扁平化，轉換為每個結構欄位對應一欄。其他欄位保持不變。

combine_chunks

( *args **kwargs )

參數

memory_pool (MemoryPool，預設值為 None) — 用於記憶體分配（若有需要），否則使用預設記憶體池。

透過合併此表格現有的區塊 (chunks) 來建立一個新表格。

每個欄位的 ChunkedArray 中的所有底層區塊都會被串接成零個或一個區塊。

cast

( target_schema *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，這會刪除任何現有的元數據）來建立表格的淺拷貝。

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 (Table 列表或 pyarrow.Table 列表) — 表格列表。
axis ({0, 1}，預設值為 0，代表跨列) — 連接的軸，其中 0 代表跨列（垂直），1 代表跨欄（水平）。

於 1.6.0 版本加入

從表格列表建立 ConcatenationTable。

公用程式 (Utils)

datasets.table.concat_tables

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

參數

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

由表格載入的快取檔案路徑列表。

取得由表格載入的快取檔案。當表格的部分資料透過記憶體映射 (memory mapping) 從磁碟載入時，會使用快取檔案。

在 GitHub 上更新

←載入方法公用程式→

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