MLTable 類別

參考

表示 MLTable。

MLTable 會定義一系列的延遲評估、不可變的作業，以從數據源載入數據。除非要求 MLTable 傳遞數據，否則不會從來源載入數據。

初始化新的MLTable。

此建構函式不應該直接叫用。 MLTable 旨在使用 load來建立。

繼承: builtins.object

MLTable

建構函式

MLTable()

方法

convert_column_types	新增轉換步驟，將指定的數據行轉換成其各自的指定新類型。 `from mltable import DataType data_types = { 'ID': DataType.to_string(), 'Date': DataType.to_datetime('%d/%m/%Y %I:%M:%S %p'), 'Count': DataType.to_int(), 'Latitude': DataType.to_float(), 'Found': DataType.to_bool(), 'Stream': DataType.to_stream() }`
drop_columns	新增轉換步驟，以從數據集卸除指定的數據行。如果空的清單、Tuple 或 set 未卸除任何專案，重複的數據行會引發 UserErrorException。嘗試卸除MLTable.traits.timestamp_column或MLTable.traits.index_columns中的數據行將會引發UserErrorException。
extract_columns_from_partition_format	新增轉換步驟，以使用每個路徑的數據分割資訊，並根據指定的數據分割格式將它們擷取到數據行。格式元件 '{column_name}' 會建立字串數據行，而 '{column_name：yyyy/MM/dd/HH/mm/ss}' 會建立 datetime 數據行，其中 'yyyy'、'MM'、'dd'、'HH'、'mm' 和 'ss' 用來擷取日期時間類型的年、月、日、小時、分鐘和秒。格式應該從第一個分割區索引鍵的位置開始，直到檔案路徑的結尾為止。例如，假設路徑 '/Accounts/2019/01/01/data.csv'，其中分割區是依部門名稱和時間， partition_format='/{Department}/{PartitionDate：yyyy/MM/dd}/data.csv' 會建立字符串數據行 'Department'，其值為 'Accounts' 和日期時間數據行 'PartitionDate'，其值為 '2019-01-01'。
filter	篩選數據，只保留符合指定表達式的記錄。
get_partition_count	傳回與這個 MLTable 相關聯之數據基礎的數據分割數目。
keep_columns	新增轉換步驟來保留指定的數據行，並從數據集卸除所有其他數據行。如果空的清單、Tuple 或 set 未卸除任何專案，重複的數據行會引發 UserErrorException。如果未明確保留MLTable.traits.timestamp_column中的數據行或MLTable.traits.index_columns中的數據行，則UserErrorException是不雅的。
random_split	隨機將此 MLTable 分割成兩個 MLTable，其中一個具有大約原始 MLTable 數據的百分比，另一個則具有其餘部分 (1-“percent”%) 。
save	將此 MLTable 儲存為 MLTable YAML 檔案，& 其指定目錄路徑的路徑。如果未指定 path ，預設為目前的工作目錄。如果路徑不存在，則會建立路徑。如果 path 是遠端的，基礎資料存放區必須已經存在。如果 path 是本機目錄 & 不是絕對目錄，則會成為絕對目錄。如果路徑指向檔案，則會引發UserErrorException。如果 path 是已儲存一或多個檔案的目錄路徑， (包括 MLTable YAML 檔案) 且覆寫設定為 False 或 'fail' - 則會引發 UserErrorException。如果 path 是遠端的，則任何未指定為共置路徑的本機檔案路徑， (相對於從) 載入 MLTable 的目錄，都會引發 UserErrorException。共置控件如何將相關聯的路徑儲存至路徑。如果為 True，則會將檔案複製到 MLTable YAML 檔案旁的路徑做為相對檔案路徑。否則不會複製相關聯的檔案，遠端路徑會維持為指定狀態，而本機檔案路徑會視需要與路徑重新導向相對。請注意，False 可能會導致不建議使用非共置 MLTable YAML 檔案，此外，如果 path 是遠端，這會導致 UserErrorException 產生 UserErrorException，因為遠端 URI 不支持相對路徑重新導向。請注意，如果 MLTable 是以程式設計方式使用本機相對路徑 from_paths () 或 from_read_delimited_files () 等方法建立，則 MLTable 目錄路徑會假設為目前的工作目錄。儲存新的 MLTable & 相關聯的數據檔到具有現有 MLTable 檔案的目錄時，請留意 & 目錄在儲存新檔案之前，不會清除該目錄的相關數據檔。儲存新檔案之後，現有的數據檔可以保存，特別是在現有的數據檔沒有符合任何新數據檔的名稱時。如果新的 MLTable 在其路徑下包含模式指示項，這可能會不小心將現有的數據檔與新的 MLTable 產生關聯，以改變 MLTable。如果此 MLTable 中的檔案路徑指向路徑中的現有檔案，但具有不同的 URI，如果覆寫為「失敗」或「略過」，則不會覆寫現有的檔案 (亦即略過) 。
select_partitions	新增轉換步驟以選取數據分割。
show	擷取這個MLTable的第一個計數數據列作為 Pandas 數據框架。
skip	新增轉換步驟，以略過這個MLTable的第一個計數數據列。
take	新增轉換步驟，以選取此 MLTable 的第一個計數數據列。
take_random_sample	新增轉換步驟，以隨機選取此MLTable的每個數據列，並有機率。機率必須介於 [0， 1] 範圍內。可以選擇性地設定隨機種子。
to_pandas_dataframe	將所有記錄從 MLTable 檔案中指定的路徑載入 Pandas DataFrame。
validate	驗證是否可以載入這個MLTable的數據，需要MLTable的數據源 () 才能從目前的計算存取。

convert_column_types

新增轉換步驟，將指定的數據行轉換成其各自的指定新類型。


   from mltable import DataType
       data_types = {
           'ID': DataType.to_string(),
           'Date': DataType.to_datetime('%d/%m/%Y %I:%M:%S %p'),
           'Count': DataType.to_int(),
           'Latitude': DataType.to_float(),
           'Found': DataType.to_bool(),
           'Stream': DataType.to_stream()
       }

convert_column_types(column_types)

參數

名稱	Description
column_types 必要	dict[Union[Tuple[str], str], DataType] 數據行的字典：輸入使用者想要轉換

傳回

類型	Description
MLTable	具有新增轉換步驟的MLTable

drop_columns

新增轉換步驟，以從數據集卸除指定的數據行。如果空的清單、Tuple 或 set 未卸除任何專案，重複的數據行會引發 UserErrorException。

嘗試卸除MLTable.traits.timestamp_column或MLTable.traits.index_columns中的數據行將會引發UserErrorException。

drop_columns(columns: str | List[str] | Tuple[str] | Set[str])

參數

名稱	Description
columns 必要	Union[str, list[str], <xref:builtin.tuple>[str], <xref:builtin.set>[str]] 要從這個 MLTable 卸除的數據行 ()

傳回

類型	Description
MLTable	具有新增轉換步驟的MLTable

extract_columns_from_partition_format

新增轉換步驟，以使用每個路徑的數據分割資訊，並根據指定的數據分割格式將它們擷取到數據行。

格式元件 '{column_name}' 會建立字串數據行，而 '{column_name：yyyy/MM/dd/HH/mm/ss}' 會建立 datetime 數據行，其中 'yyyy'、'MM'、'dd'、'HH'、'mm' 和 'ss' 用來擷取日期時間類型的年、月、日、小時、分鐘和秒。

格式應該從第一個分割區索引鍵的位置開始，直到檔案路徑的結尾為止。例如，假設路徑 '/Accounts/2019/01/01/data.csv'，其中分割區是依部門名稱和時間， partition_format='/{Department}/{PartitionDate：yyyy/MM/dd}/data.csv' 會建立字符串數據行 'Department'，其值為 'Accounts' 和日期時間數據行 'PartitionDate'，其值為 '2019-01-01'。

extract_columns_from_partition_format(partition_format)

參數

名稱	Description
partition_format 必要	str 用來將數據擷取到數據行的數據分割格式

傳回

類型	Description
MLTable	數據分割格式設定為指定格式的MLTable

filter

篩選數據，只保留符合指定表達式的記錄。

filter(expression)

參數

名稱	Description
expression 必要	string 要評估的運算式。

傳回

類型	Description
MLTable	篩選之後的MLTable

備註

表達式的開頭是使用數據行名稱編製 mltable 的索引。它們支持各種函式和運算符，而且可以使用邏輯運算符來結合。當數據提取發生，而不是定義數據時，產生的表達式將會針對每個記錄進行延遲評估。


   filtered_mltable = mltable.filter('feature_1 == "5" and target > "0.5)"')
   filtered_mltable = mltable.filter('col("FBI Code") == "11"')

get_partition_count

傳回與這個 MLTable 相關聯之數據基礎的數據分割數目。

get_partition_count() -> int

傳回

類型	Description
int	此 MLTable 中的數據分割區

keep_columns

新增轉換步驟來保留指定的數據行，並從數據集卸除所有其他數據行。如果空的清單、Tuple 或 set 未卸除任何專案，重複的數據行會引發 UserErrorException。

如果未明確保留MLTable.traits.timestamp_column中的數據行或MLTable.traits.index_columns中的數據行，則UserErrorException是不雅的。

keep_columns(columns: str | List[str] | Tuple[str] | Set[str])

參數

名稱	Description
columns 必要	Union[str, list[str], <xref:builtin.tuple>[str], <xref:builtin.set>[str]] 此 MLTable 中的數據行 () 保留

傳回

類型	Description
MLTable	具有新增轉換步驟的MLTable

random_split

隨機將此 MLTable 分割成兩個 MLTable，其中一個具有大約原始 MLTable 數據的百分比，另一個則具有其餘部分 (1-“percent”%) 。

random_split(percent=0.5, seed=None)

參數

名稱	Description
percent 必要	Union[int, float] 要分割的MLTable百分比
seed 必要	Optional[int] 選擇性隨機種子

傳回

類型	Description
Tuple[MLTable, MLTable]	具有此 MLTable 數據的兩個 MLTable 會以「百分比」分割成兩個 MLTable

save

將此 MLTable 儲存為 MLTable YAML 檔案，& 其指定目錄路徑的路徑。

如果未指定 path ，預設為目前的工作目錄。如果路徑不存在，則會建立路徑。如果 path 是遠端的，基礎資料存放區必須已經存在。如果 path 是本機目錄 & 不是絕對目錄，則會成為絕對目錄。

如果路徑指向檔案，則會引發UserErrorException。如果 path 是已儲存一或多個檔案的目錄路徑， (包括 MLTable YAML 檔案) 且覆寫設定為 False 或 'fail' - 則會引發 UserErrorException。如果 path 是遠端的，則任何未指定為共置路徑的本機檔案路徑， (相對於從) 載入 MLTable 的目錄，都會引發 UserErrorException。

共置控件如何將相關聯的路徑儲存至路徑。如果為 True，則會將檔案複製到 MLTable YAML 檔案旁 的路徑 做為相對檔案路徑。否則不會複製相關聯的檔案，遠端路徑會維持為指定狀態，而本機檔案路徑會視需要與路徑重新導向相對。請注意，False 可能會導致不建議使用非共置 MLTable YAML 檔案，此外，如果 path 是遠端，這會導致 UserErrorException 產生 UserErrorException，因為遠端 URI 不支持相對路徑重新導向。

請注意，如果 MLTable 是以程式設計方式使用本機相對路徑 from_paths () 或 from_read_delimited_files () 等方法建立，則 MLTable 目錄路徑會假設為目前的工作目錄。

儲存新的 MLTable & 相關聯的數據檔到具有現有 MLTable 檔案的目錄時，請留意 & 目錄在儲存新檔案之前，不會清除該目錄的相關數據檔。儲存新檔案之後，現有的數據檔可以保存，特別是在現有的數據檔沒有符合任何新數據檔的名稱時。如果新的 MLTable 在其路徑下包含模式指示項，這可能會不小心將現有的數據檔與新的 MLTable 產生關聯，以改變 MLTable。

如果此 MLTable 中的檔案路徑指向路徑中的現有檔案，但具有不同的 URI，如果覆寫為「失敗」或「略過」，則不會覆寫現有的檔案 (亦即略過) 。

save(path=None, overwrite=True, colocated=False, show_progress=False, if_err_remove_files=True)

參數

名稱	Description
path 必要	str 要儲存的目錄路徑，預設為目前的工作目錄
colocated 必要	bool 如果為 True，請將此 MLTable 中本機 & 遠端檔案路徑的複本儲存為相對路徑。否則不會複製檔案，而且遠端檔案路徑會儲存為已儲存的MLTable YAML檔案和本機檔案路徑，作為路徑重新導向的相對檔案路徑。如果 path 是遠端 & 此 MLTable 包含本機檔案路徑，則會引發 UserErrorException。
overwrite 必要	Union[bool, str, <xref:mltable.MLTableSaveOverwriteOptions>] 如何處理路徑下可能已經存在的 MLTable YAML 檔案和相關聯的檔案。選項為「覆寫」 (或 True) 取代任何現有的檔案、「失敗」 (或 False) ，以在檔案已經存在時引發錯誤，或「略過」讓現有檔案保持原樣。也可以使用設定 <xref:mltable.MLTableSaveOverwriteOptions>。
show_progress 必要	bool 顯示複製進度至 stdout
if_err_remove_files 必要	bool 如果在儲存期間發生任何錯誤，請移除任何成功儲存的檔案，讓作業不可部分完成

傳回

類型	Description
MLTable	這個 MLTable 實例

select_partitions

新增轉換步驟以選取數據分割。

select_partitions(partition_index_list)

參數

名稱	Description
partition_index_list 必要	list of int 數據分割索引的清單

傳回

類型	Description
MLTable	已更新數據分割大小的MLTable

備註

下列代碼段示範如何使用select_partitions API，從提供的 MLTable 選取的數據分割。


   partition_index_list = [1, 2]
   mltable = mltable.select_partitions(partition_index_list)

show

擷取這個MLTable的第一個計數數據列作為 Pandas 數據框架。

show(count=20)

參數

名稱	Description
count 必要	int 要選取之數據表頂端的數據列數目

傳回

類型	Description
<xref:Pandas> <xref:Dataframe>	MLTable 的第一個計數數據列

skip

新增轉換步驟，以略過這個MLTable的第一個計數數據列。

skip(count)

參數

名稱	Description
count 必要	int 要略過的數據列數目

傳回

類型	Description
	具有新增轉換步驟的MLTable

take

新增轉換步驟，以選取此 MLTable 的第一個計數數據列。

take(count=20)

參數

名稱	Description
count 必要	int 要選取之數據表頂端的數據列數目

傳回

類型	Description
MLTable	已新增「採取」轉換步驟的MLTable

take_random_sample

新增轉換步驟，以隨機選取此MLTable的每個數據列，並有機率。機率必須介於 [0， 1] 範圍內。可以選擇性地設定隨機種子。

take_random_sample(probability, seed=None)

參數

名稱	Description
probability 必要	選取每個數據列的機會
seed 必要	Optional[int] 選擇性隨機種子

傳回

類型	Description
MLTable	具有新增轉換步驟的MLTable

to_pandas_dataframe

將所有記錄從 MLTable 檔案中指定的路徑載入 Pandas DataFrame。

to_pandas_dataframe()

傳回

類型	Description
DataFrame	Pandas Dataframe 包含此 MLTable 中路徑的記錄

備註

下列代碼段示範如何使用 to_pandas_dataframe api 來取得對應至所提供MLTable的 pandas 資料框架。


   from mltable import load
   tbl = load('.\samples\mltable_sample')
   pdf = tbl.to_pandas_dataframe()
   print(pdf.shape)

validate

驗證是否可以載入這個MLTable的數據，需要MLTable的數據源 () 才能從目前的計算存取。

validate()

傳回

類型	Description
None	無

屬性

partition_keys

傳回分割區索引鍵。

傳回

類型	Description
list[str]	分割區索引鍵

paths

傳回字典清單，其中包含提供給這個MLTable的原始路徑。相對本機檔案路徑假設相對於載入這個MLTable實例之MLTable YAML 檔案的目錄。

傳回

類型	Description
list[dict[str, str]]	包含 MLTable 中所指定路徑的聽寫清單

共用方式為