表類

每個 Dataset 物件都由一個 PyArrow 表支援。表可以從磁碟（記憶體對映）或記憶體中載入。有幾種表型別可用，它們都繼承自 table.Table。

Table

class datasets.table.Table

( table: Table )

透過組合方式包裝一個 pyarrow 表。這是 InMemoryTable、MemoryMappedTable 和 ConcatenationTable 的基類。

它實現了 pyarrow 表類的所有基本屬性/方法，但表的轉換方法除外：slice、filter、flatten、combine_chunks、cast、add_column、append_column、remove_column、set_column、rename_columns 和 drop。

這些方法的實現在子類中有所不同。

validate

< 來源 >

( *args **kwargs )

引數

full (bool，預設為 False) — 如果為 True，執行開銷大的檢查，否則僅執行開銷小的檢查。

引發

pa.lib.ArrowInvalid

pa.lib.ArrowInvalid — 如果驗證失敗

執行驗證檢查。如果驗證失敗，則會引發異常。

預設情況下，只執行開銷小的驗證檢查。傳入 full=True 進行徹底的驗證檢查（可能為 O(n)）。

equals

< 來源 >

( *args **kwargs ) → bool

引數

other (Table) — 用於比較的表。
check_metadata bool，預設為 False) — 是否也檢查模式元資料的相等性。

布林值

檢查兩個表的內容是否相等。

to_batches

< 來源 >

( *args **kwargs )

引數

max_chunksize (int，預設為 None) — RecordBatch 塊的最大大小。單個塊的大小可能更小，具體取決於單個列的塊佈局。

將錶轉換為（連續的）RecordBatch 物件列表。

to_pydict

< 來源 >

( *args **kwargs ) → dict

字典

將錶轉換為 dict 或 OrderedDict。

to_pandas

< 來源 >

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

引數

memory_pool (MemoryPool，預設為 None) — 用於分配記憶體的 Arrow MemoryPool。如果未傳遞，則使用預設的記憶體池。
strings_to_categorical (bool，預設為 False) — 將字串（UTF8）和二進位制型別編碼為 pandas.Categorical。
categories (list，預設為 空列表) — 應作為 pandas.Categorical 返回的欄位列表。僅適用於類表資料結構。
zero_copy_only (bool，預設為 False) — 如果此函式呼叫需要複製底層資料，則引發 ArrowException。
integer_object_nulls (bool，預設為 False) — 將帶空值的整數轉換為物件。
date_as_object (bool，預設為 True) — 將日期轉換為物件。如果為 False，則轉換為 datetime64[ns] 型別。
timestamp_as_object (bool，預設為 False) — 將非納秒時間戳 (np.datetime64) 轉換為物件。如果您有不適合納秒時間戳正常日期範圍（公元 1678 年 - 公元 2262 年）的時間戳，這會很有用。如果為 False，則所有時間戳都將轉換為 datetime64[ns] 型別。
use_threads (bool，預設為 True) — 是否使用多執行緒並行化轉換。
deduplicate_objects (bool，預設為 False) — 建立時不要建立 Python 物件的多個副本，以節省記憶體使用。轉換速度會變慢。
ignore_metadata (bool，預設為 False) — 如果為 True，不使用 ‘pandas’ 元資料來重建 DataFrame 索引（如果存在）。
safe (bool，預設為 True) — 對於某些資料型別，需要進行型別轉換才能將資料儲存在 pandas DataFrame 或 Series 中（例如，時間戳在 pandas 中總是儲存為納秒）。此選項控制它是否是安全轉換。
split_blocks (bool，預設為 False) — 如果為 True，在從 RecordBatch 或 Table 建立 pandas.DataFrame 時，為每列生成一個內部“塊”。雖然這可以暫時減少記憶體，但請注意，各種 pandas 操作可能會觸發“合併”，這可能會導致記憶體使用量激增。
self_destruct (bool，預設為 False) — 實驗性功能：如果為 True，在將 Arrow 物件轉換為 pandas 時嘗試釋放原始 Arrow 記憶體。如果您在使用此選項呼叫 to_pandas 後再使用該物件，將會導致程式崩潰。
types_mapper (function，預設為 None) — 一個將 pyarrow DataType 對映到 pandas ExtensionDtype 的函式。這可用於覆蓋內建 pyarrow 型別的預設 pandas 型別轉換，或在表模式中缺少 pandas_metadata 時使用。該函式接收一個 pyarrow DataType，並期望返回一個 pandas ExtensionDtype，或者如果該型別應使用預設轉換，則返回 None。如果您有一個字典對映，可以傳遞 dict.get 作為函式。

pandas.Series 或 pandas.DataFrame

pandas.Series 或 pandas.DataFrame，取決於物件型別。

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

to_string

< 來源 >

( *args **kwargs )

field

< 來源 >

( *args **kwargs )

引數

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

透過列名或數字索引選擇一個模式欄位。

column

< 來源 >

( *args **kwargs )

引數

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

透過列名或數字索引選擇一列。

itercolumns

< 來源 >

( *args **kwargs )

按數值順序迭代所有列的迭代器。

schema

< 來源 >

( )

表及其列的模式。

columns

< 來源 >

( )

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

num_columns

< 來源 >

( )

此表中的列數。

num_rows

< 來源 >

( )

此表中的行數。

根據表的定義，所有列具有相同的行數。

shape

< 來源 >

( ) → (int, int)

(int, int)

行數和列數。

表的維度：(#行數, #列數)。

nbytes

< 來源 >

( )

表元素所消耗的總位元組數。

InMemoryTable

class datasets.table.InMemoryTable

< 來源 >

( table: Table )

當表被載入到使用者的 RAM 中時，該表被稱為記憶體中的表。

對其進行 Pickling 操作會使用記憶體複製所有資料。它的實現很簡單，直接使用底層的 pyarrow 表方法。

這與 MemoryMapped 表不同，對於後者，Pickling 不會將所有資料複製到記憶體中。對於 MemoryMapped，unpickling 操作會從磁碟重新載入表。

當資料適合記憶體時，必須使用 InMemoryTable，而 MemoryMapped 則保留用於比記憶體更大的資料，或者當您希望應用程式的記憶體佔用保持較低時。

validate

< 來源 >

( *args **kwargs )

引數

full (bool，預設為 False) — 如果為 True，執行開銷大的檢查，否則僅執行開銷小的檢查。

引發

pa.lib.ArrowInvalid

pa.lib.ArrowInvalid — 如果驗證失敗

執行驗證檢查。如果驗證失敗，則會引發異常。

預設情況下，只執行開銷小的驗證檢查。傳入 full=True 進行徹底的驗證檢查（可能為 O(n)）。

equals

< 原始碼 >

( *args **kwargs ) → bool

引數

other (Table) — 用於比較的表。
check_metadata (bool, 預設為 False) — 是否也檢查 schema 元資料是否相等。

布林值

檢查兩個表的內容是否相等。

to_batches

< 原始碼 >

( *args **kwargs )

引數

max_chunksize (int, 預設為 None) — RecordBatch 塊的最大尺寸。根據各個列的塊佈局，單個塊可能會更小。

將錶轉換為（連續的）RecordBatch 物件列表。

to_pydict

< 原始碼 >

( *args **kwargs ) → dict

字典

將錶轉換為 dict 或 OrderedDict。

to_pandas

< 原始碼 >

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

引數

memory_pool (MemoryPool, 預設為 None) — 用於分配記憶體的 Arrow MemoryPool。如果未傳遞，則使用預設記憶體池。
strings_to_categorical (bool, 預設為 False) — 將字串（UTF8）和二進位制型別編碼為 pandas.Categorical。
categories (list, 預設為 空列表) — 應作為 pandas.Categorical 返回的欄位列表。僅適用於類似表的資料結構。
zero_copy_only (bool, 預設為 False) — 如果此函式呼叫需要複製底層資料，則引發 ArrowException。
integer_object_nulls (bool, 預設為 False) — 將帶空值的整數轉換為物件。
date_as_object (bool, 預設為 True) — 將日期轉換為物件。如果為 False，則轉換為 datetime64[ns] dtype。
timestamp_as_object (bool, 預設為 False) — 將非納秒級的時間戳（np.datetime64）轉換為物件。這對於處理不適合納秒級時間戳正常日期範圍（公元 1678 年至 2262 年）的時間戳非常有用。如果為 False，所有時間戳都將轉換為 datetime64[ns] dtype。
use_threads (bool, 預設為 True) — 是否使用多執行緒並行化轉換。
deduplicate_objects (bool, 預設為 False) — 建立時不要為 Python 物件建立多個副本，以節省記憶體使用。轉換速度會變慢。
ignore_metadata (bool, 預設為 False) — 如果為 True，則不使用 'pandas' 元資料來重建 DataFrame 索引（如果存在）。
safe (bool, 預設為 True) — 對於某些資料型別，需要進行轉換才能將其儲存在 pandas DataFrame 或 Series 中（例如，時間戳在 pandas 中總是以納秒為單位儲存）。此選項控制這是否為安全轉換。
split_blocks (bool, 預設為 False) — 如果為 True，在從 RecordBatch 或 Table 建立 pandas.DataFrame 時，為每列生成一個內部“塊”。雖然這可以暫時減少記憶體使用，但請注意，各種 pandas 操作可能會觸發“合併”，從而可能導致記憶體使用量激增。
self_destruct (bool, 預設為 False) — 實驗性功能：如果為 True，在將 Arrow 物件轉換為 pandas 時，嘗試釋放原始 Arrow 記憶體。如果在使用此選項呼叫 to_pandas 後再使用該物件，程式將會崩潰。
types_mapper (function, 預設為 None) — 一個將 pyarrow DataType 對映到 pandas ExtensionDtype 的函式。這可以用於覆蓋內建 pyarrow 型別的預設 pandas 型別轉換，或者在表 schema 中缺少 pandas_metadata 時使用。該函式接收一個 pyarrow DataType，並應返回一個 pandas ExtensionDtype，如果該型別應使用預設轉換，則返回 None。如果你有一個對映字典，可以將 dict.get 作為函式傳遞。

pandas.Series 或 pandas.DataFrame

pandas.Series 或 pandas.DataFrame，取決於物件型別。

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

to_string

< 原始碼 >

( *args **kwargs )

field

< 原始碼 >

( *args **kwargs )

引數

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

透過列名或數字索引選擇一個模式欄位。

column

< 原始碼 >

( *args **kwargs )

引數

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

透過列名或數字索引選擇一列。

itercolumns

< 原始碼 >

( *args **kwargs )

按數值順序迭代所有列的迭代器。

schema

< 原始碼 >

( )

表及其列的模式。

columns

< 原始碼 >

( )

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

num_columns

< 原始碼 >

( )

此表中的列數。

num_rows

< 原始碼 >

( )

此表中的行數。

根據表的定義，所有列具有相同的行數。

shape

< 原始碼 >

( ) → (int, int)

(int, int)

行數和列數。

表的維度：(#行數, #列數)。

nbytes

< 原始碼 >

( )

表元素所消耗的總位元組數。

column_names

< 原始碼 >

( )

表的列名。

slice

< 原始碼 >

( offset = 0 length = None )

引數

offset (int, 預設為 0) — 從表開頭切片的偏移量。
length (int, 預設為 None) — 切片的長度（預設為從偏移量開始直到表尾）。

計算此表的零複製切片。

過濾器

< 原始碼 >

( *args **kwargs )

從表中選擇記錄。有關完整用法，請參閱 pyarrow.compute.filter。

flatten

< 原始碼 >

( *args **kwargs )

引數

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

展平此表。每個具有結構體型別的列都被展平為每個結構體欄位一列。其他列保持不變。

combine_chunks

< 原始碼 >

( *args **kwargs )

引數

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

透過組合此表所擁有的塊來建立一個新表。

每列 ChunkedArray 中的所有底層塊都被連線成零個或一個塊。

cast

< 原始碼 >

( *args **kwargs )

引數

target_schema (Schema) — 要轉換到的 schema，欄位的名稱和順序必須匹配。
safe (bool, 預設為 True) — 檢查溢位或其他不安全的轉換。

將表值轉換為另一個 schema。

replace_schema_metadata

< 原始碼 >

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

引數

metadata (dict, 預設為 None) —

datasets.table.Table

shallow_copy

實驗性功能：透過將 schema 鍵值元資料替換為指定的新元資料（可以是 None，表示刪除任何現有元資料），建立表的淺複製。

add_column

< 原始碼 >

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

引數

i (int) — 放置列的索引。
field_ (Union[str, pyarrow.Field]) — 如果傳遞的是字串，則型別將從列資料中推斷。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列資料。

datasets.table.Table

添加了傳入列的新表。

在指定位置向表中新增一列。

返回一個添加了列的新表，原始表物件保持不變。

append_column

< 原始碼 >

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

引數

field_ (Union[str, pyarrow.Field]) — 如果傳遞的是字串，則型別將從列資料中推斷。
column (Union[pyarrow.Array, List[pyarrow.Array]]) — 列資料。

datasets.table.Table

添加了傳入列的新表。

在列的末尾追加列。

資料集

表類

Table

class datasets.table.Table

validate

equals

to_batches

to_pydict

to_pandas

to_string

field

column

itercolumns

schema

columns

num_columns

num_rows

shape

nbytes

InMemoryTable

class datasets.table.InMemoryTable

validate

equals

to_batches

to_pydict

to_pandas

to_string

field

column

itercolumns

schema

columns

num_columns

num_rows

shape

nbytes

column_names

slice

過濾器

flatten

combine_chunks

cast

replace_schema_metadata

add_column

append_column

remove_column

set_column

rename_columns

選擇

drop

from_file

from_buffer

from_pandas

from_arrays

from_pydict

from_batches

MemoryMappedTable

class datasets.table.MemoryMappedTable

validate

equals

to_batches

to_pydict

to_pandas

to_string

field

column

itercolumns

schema

columns

num_columns

num_rows

shape

nbytes

column_names

slice

過濾器

flatten

combine_chunks

cast

replace_schema_metadata