FileType

適用於：勾選已標記為 Databricks 執行時間 18 LTS 及以上

Important

這項功能位於 測試版 (Beta) 中。 工作區管理員可以從 「預覽 」頁面控制對此功能的存取。 請參閱 管理 Azure Databricks 預覽。

FileType 是 SQL FILE 型別的 PySpark 型別，該型別是指向非結構化檔案及其元資料的參考。 用它來宣告 FILE Python 使用者自訂函式（UDF）中的參數和回傳型別。 在 Python 中，FILE值是一個FileRef物件，用來儲存檔案的元資料並讀取其位元組。

關於 SQL 型別參考與概念概述，請參見 FILE type and FILE 型態及非結構化資料。 關於檔案處理 UDF 範例，請參見 帶有 UDF 的 Process 檔案。

Note

FILE Type 需要在無伺服器筆記本上達到 環境版本 6 或以上。 要選擇筆記本的環境版本，請參見 選擇基礎環境。

Import

from pyspark.sql.types import FileType, FileRef

FileType

FileType 是 pyspark.sql.types.DataType 的子類別。 可將其用作 UDF 的參數或回傳類型，或作為結構中的欄位類型。

FileType 不指定 MANAGED 或 EXTERNAL。 這些限定符僅適用於 FILE 資料表欄位，該欄位決定參考是被管理儲存還是外部存取。 UDF 會傳遞並回傳 FILE 參考，目標欄位決定在你將結果寫入資料表時如何儲存每個參考。

你可以以下方式使用 FileType ，這些方法同樣適用於 SQL 和 Scala UDF，以及 SQL 儲存程序：

  • 作為頂層類型。
  • 嵌套在 a StructType 或 ArrayType中。
  • 作為 的值型態 MapType，但不是作為 MapType 鍵。
  • 在 裡面 VariantType，但只限於外部檔案。

當查詢FILE返回欄位給 Python，無論是在 UDF 內部還是透過 DataFrame.collect()，每個值都是 FileRef。

檔案參考

A FileRef 是 Python 的值FILE。 它儲存檔案的元資料，並具備讀取檔案位元組及建立新參考的方法。

屬性

Attribute 類型 Description
uri str 檔案的 URI。 永遠準備好。
offset int 檔案的偏移量以位元組為單位。
size int 檔案的大小 (以位元組為單位)。
content_type str 檔案的 MIME 類型（已知時）。
checksum str 檔案中位元組的完整性權杖，形式 <algorithm>:<digest>為 。 關於已識別的演算法，請參見 校驗和。

Methods

方法 Description
as_local_file() 將 a pathlib.Path 返回檔案。 將結果傳給任何接受路徑的函式庫。 可於 Azure Databricks 計算（筆記本與 UDF 工作者）取得。 在 Databricks Connect 用戶端（例如 IDE 或本地應用程式，能在 Azure Databricks 運算之外執行程式碼）上無法提供。
open() 開啟檔案進行二進位讀取並回傳一個檔案物件。 來電者關上了門。 與 有相同的計算需求 as_local_file()。
from_bytes(content, path=None, content_type=None) 課程方法。 將（值）上傳content到 Unity 目錄的磁碟區路徑，bytes由 給出，並回傳一個 path。FileRef 如果目標路徑上已有檔案，則會失敗。 僅支援 UDF 內部。
from_local_file(local_file, path=None, content_type=None) 課程方法。 將本地檔案上傳到 Unity 目錄卷，並回傳一個 FileRef. path與content_type參數的行為如下。from_bytes 僅支援 UDF 內部。

Example

在以下程式碼中，標量 UDF 會獲得 FILE 一個值， FileRef打開影像並返回其尺寸：

from pyspark.sql.functions import col, udf
from pyspark.sql.types import FileRef, StringType
from PIL import Image

@udf(returnType=StringType())
def image_resolution(file: FileRef) -> str:
    with Image.open(file.as_local_file()) as img:
        return f"{img.width}x{img.height}"

spark.read.table("images").select(image_resolution(col("photo"))).display()

欲了解更多檔案處理 UDF 範例，包括使用 UDTF 產生檔案，請參見 帶有 UDF 的 Process 檔案。 關於一般的 UDF 編寫，請參見 Python 標量使用者定義函數（UDFs）及 Python 使用者定義表格函數（UDTFs）。

局限性

在 PySpark 中使用 FileType 有以下限制：

  • PySpark 不支援宣告 FILE MANAGED 、 FILE EXTERNAL 資料表欄位或批量擷取檔案。 這些操作用 SQL 來做。 PySpark 僅支援 FILE，作為 FileType，在 UDF 和檔案讀取中。
  • as_local_file() 且 open() 需要叢集端存取，因此無法在 Databricks Connect 用戶端使用。 建議用 UDF 或叢集運算來呼叫它們。
  • 對於 from_bytes 和 from_local_file，Python UDF 是content_type從路徑擴展推斷，而 Scala UDF 則是從檔案的魔術位元組推斷。
  • 從寫入FileRef欄位的 UDF 回傳 a FILE MANAGED 是不被支援的。
  • 註冊在 Unity 目錄中的CREATE FUNCTION UDF（）可以讀取 的 中繼資料，但無法讀取 FILE其內容，且無法建立檔案。 使用會話範圍的 UDF 來讀取檔案內容（open， ） 或建立檔案內容 （from_bytes， as_local_file， from_local_file）。
  • Last updated on