Object Table常用UDF（Java）

本文介紹在MaxCompute Object Table情境中，用於非結構化檔案中繼資料提取與格式識別的常用Java UDF，包括函數說明和使用步驟。

在 AI 資料處理情境中，對非結構化資料（如圖片、音視頻、PDF、Office 文檔等）進行中繼資料提取與預先處理，是 Object Table 的典型用途。非結構化資料存放區在 OSS 中，需要在進入模型訓練、內容理解或檢索增強（RAG）等流程前，批量提取檔案中繼資料，例如：

從映像中提取尺寸、格式、EXIF資訊等。
從音視頻檔案中擷取時間長度、採樣率、編碼格式、主要畫面格等。
從PDF或Word文檔中解析頁數、作者、建立時間等。

基於Object Table能力，MaxCompute 提供以下 Java UDF，支援在 SQL 層面對儲存在Object Storage Service中的檔案進行元資訊提取與輕量級預先處理。提取結果可用於構建結構化中繼資料表、過濾或採樣資料集，以及為 AI 特徵工程、向量化等下遊任務提供輸入。

下載 Java UDF jar包

下載 Java UDF jar包：lakehouse-udf-1.0-SNAPSHOT.jar

AI-UDF 列表

GetFileMeta

GetFileMeta用於擷取檔案的中繼資料，傳回型別為Map<String, String>。

支援的檔案格式
類型
支援格式
圖片
jpg、jpeg、png、bmp、gif、tif、tiff
音視頻
mp3、mp4、avi、wav
辦公文檔
pdf、doc、docx、ppt、pptx、xls、xlsx

方法

evaluate(Binary data, String fileFormat)
evaluate(Binary data, String fileFormat, String metadataKeyDelimiter)
evaluate(Binary data, String fileFormat, String metadataKeyDelimiter, String parseFailPolicy)
evaluate(Binary data, String fileFormat, Map<String, String> options)

options參數說明

參數名	類型	預設值	說明
`metadataKeyDelimiter`	String	`"."`	多層級中繼資料鍵名的分隔字元。（如有多層級表示，則使用該參數。）在圖片類檔案中，作為中繼資料"目錄"與"標籤"的分隔字元。例如：預設：`"EXIF.DateTimeOriginal"` 自訂`/`：`"EXIF/DateTimeOriginal"`
`password`	String	`null`	加密PDF檔案的密碼。僅對`pdf`格式有效，其他加密檔案（如Office加密文檔）暫不支援。
`parseFailPolicy`	String	`"OUTPUT_NULL"`	解析失敗時的處理策略，取值如下： OUTPUT_DEFAULT：靜默返回null。 OUTPUT_NULL：靜默返回null。 WARN_AND_NULL：輸出警告日誌後返回null。 THROW_EXCEPTION：拋出異常，中斷流程。
`metadataKeyExclusionRegex`	String	`null`	中繼資料鍵名正則過濾器，移除命中Regex的中繼資料項，多個規則以逗號分隔。例如： `"Photoshop."`（移除鍵名以`Photoshop`開頭的條目） `".Path Info.*"`（移除鍵名含`Path Info`子串的條目）

GetFileFormat

GetFileFormat用於提取檔案的詳細格式，例如json、csv、orc、parquet等，傳回型別為String。

方法

用法一：根據檔案名稱提取格式

evaluate(String fileName, String parseFailPolicy)

用法二：根據位元據和檔案名稱提取格式。

evaluate(Binary data, String fileName, String parseFailPolicy)

options參數說明
parseFailPolicy：解析失敗時的處理策略。String類型。預設值為"OUTPUT_NULL"，取值如下：
- OUTPUT_DEFAULT：靜默返回null。
- OUTPUT_NULL：靜默返回null。
- WARN_AND_NULL：輸出警告日誌後返回null。
- THROW_EXCEPTION：拋出異常，中斷流程。

GetFileMediaType

GetFileMediaType用於根據IANA註冊表檢測檔案的頂級MIME媒體類型，傳回型別為String。

支援媒體類型：
- application（應用）
- audio（音頻）
- example（樣本）
- font（字型）
- haptics（觸覺）
- image（映像）
- message（訊息）
- model（模型）
- multipart（多部分）
- text（文本）
- video（視頻）

方法

用法一：根據檔案名稱提取格式

evaluate(String fileName, String parseFailPolicy)

用法二：根據位元據和檔案名稱提取格式

evaluate(Binary data, String fileName, String parseFailPolicy)

options參數說明
parseFailPolicy：解析失敗時的處理策略。String類型。預設值為"OUTPUT_NULL"，取值如下：
- OUTPUT_DEFAULT：靜默返回null。
- OUTPUT_NULL：靜默返回null。
- WARN_AND_NULL：輸出警告日誌後返回null。
- THROW_EXCEPTION：拋出異常，中斷流程。

GetFileContentType

GetFileContentType用於返迴文件的完整MIME內容類型（Content-Type），傳回型別為String。

方法
- 用法一：根據檔案名稱檢測內容類型
```
evaluate(String fileName, String parseFailPolicy)
```
- 用法二： 根據位元據和檔案名稱檢測內容類型
```
evaluate(Binary data, String fileName, String parseFailPolicy)
```
options參數說明
parseFailPolicy：解析失敗時的處理策略。String類型。預設值為"OUTPUT_NULL"，取值如下：
- OUTPUT_DEFAULT：靜默返回null。
- OUTPUT_NULL：靜默返回null。
- WARN_AND_NULL：輸出警告日誌後返回null。
- THROW_EXCEPTION：拋出異常，中斷流程。

GetFileName

GetFileName用於從檔案路徑中提取檔案名稱，傳回型別為String。

方法

evaluate(String filePath, String parseFailPolicy)

options參數說明
parseFailPolicy：解析失敗時的處理策略。String類型。預設值為"OUTPUT_NULL"，取值如下：
- OUTPUT_DEFAULT：靜默返回null。
- OUTPUT_NULL：靜默返回null。
- WARN_AND_NULL：輸出警告日誌後返回null。
- THROW_EXCEPTION：拋出異常，中斷流程。

使用樣本

準備資料
登入Object Storage Service控制台，並上傳資料。本樣本中使用測試資料如下：object_table_demo_files.zip。

上傳UDF jar包，建立UDF函數

下載 Java UDF jar包：lakehouse-udf-1.0-SNAPSHOT.jar

本樣本使用odpscmd，其他Jar包上傳方法參考UDF開發（Java）。

-- 進入odpscmd環境
SET odps.sql.allow.namespace.schema=true;
SET odps.namespace.schema=true;
SET odps.sql.type.system.odps2=true;

-- 建立object table
DROP TABLE IF EXISTS udf_demo;
CREATE OBJECT TABLE udf_demo 
LOCATION 'oss://<endpoint>/<bucket>/path/to/files/'; -- location填上一步驟上傳的檔案的目錄
-- 重新整理object table元資訊
ALTER TABLE udf_demo refresh metadata;

-- 上傳 udf jar 後建立functions
add jar /path/to/lakehouse-udf-1.0-SNAPSHOT.jar;  -- 注意這裡需要改為本地udf jar的絕對路徑
create function get_file_name as 'com.aliyun.odps.lakehouse.udf.GetFileName' using 'lakehouse-udf-1.0-SNAPSHOT.jar';
create function get_file_media_type as 'com.aliyun.odps.lakehouse.udf.GetFileMediaType' using 'lakehouse-udf-1.0-SNAPSHOT.jar';
create function get_file_content_type as 'com.aliyun.odps.lakehouse.udf.GetFileContentType' using 'lakehouse-udf-1.0-SNAPSHOT.jar';
create function get_file_format as 'com.aliyun.odps.lakehouse.udf.GetFileFormat' using 'lakehouse-udf-1.0-SNAPSHOT.jar';
create function get_file_meta as 'com.aliyun.odps.lakehouse.udf.GetFileMeta' using 'lakehouse-udf-1.0-SNAPSHOT.jar';

在object table中使用函數

set odps.sql.allow.namespace.schema=true;
set odps.namespace.schema=true;
set odps.sql.type.system.odps2=true;

-- 查詢檔案內容類型 & 檔案媒體類型
select 
  key, 
  get_file_content_type(key, "OUTPUT_DEFAULT"), 
  get_file_media_type(key, "OUTPUT_DEFAULT") 
from udf_demo;
-- 結果：
+------------+------------+------------+
| key        | _c1        | _c2        | 
+------------+------------+------------+
| lancePaper.pdf | application/pdf | application | 
| sample.avi | video/x-msvideo | video      | 
| sample.doc | application/msword | application | 
| sample.gif | image/gif  | image      | 
| sample.jpeg | image/jpeg | image      | 
| sample.jpg | image/jpeg | image      | 
| sample.mp3 | audio/mpeg | audio      | 
| sample.mp4 | video/mp4  | video      | 
| sample.png | image/png  | image      | 
| sample.ppt | application/vnd.ms-powerpoint | application | 
| sample.wav | audio/vnd.wave | audio      | 
| sample.xls | application/vnd.ms-excel | application | 
+------------+------------+------------+

-- 查詢檔案格式&中繼資料 (假設檔案名稱中都有格式尾碼, 例如 "xxx.pdf")
select 
  key,
  get_file_format(key, 'OUTPUT_DEFAULT'), 
  get_file_meta(
    -- get_data_from_oss函數可以從oss上擷取檔案內容
    get_data_from_oss('three_tier_model.default.udf_demo', key), -- binary形式的檔案內容
    get_file_format(key, 'OUTPUT_DEFAULT')  -- 檔案類型, 如 pdf/mp3/avi/jpg 等
  )
from udf_demo;

常見問題

使用UDF時遇到Java類衝突報錯如何處理？

錯誤資訊

java.lang.LinkageError: loader constraint violation: 
  when resolving overridden method "org.apache.xerces.jaxp.SAXParserImpl.parse(Lorg/xml/sax/InputSource;Lorg/xml/sax/helpers/DefaultHandler;)V" 
  the class loader (instance of com/aliyun/odps/udf/impl/utils/OdpsUserCodeLoaderFactory$ChildFirstLoader) of the current class, org/apache/xerces/jaxp/SAXParserImpl, 
  and its superclass loader (instance of <bootloader>), have different Class objects for the type org/xml/sax/helpers/DefaultHandler used in the signature
    at org.apache.xerces.jaxp.SAXParserFactoryImpl.newSAXParser(Unknown Source)
    at org.apache.tika.mime.MimeTypesReader.newSAXParser(MimeTypesReader.java:223)

問題原因
說明本文檔提供的 UDF Jar 可能與您的專案空間中已存在的一些資源（如已存在的Java UDF）有類衝突。
解決方案
建立一個新的 schema，並在新的 schema 空間裡上傳 UDF Jar 後再建立 UDF 並使用。如果上述方案無效，可建立新的Project後再使用該功能。

類型	支援格式
圖片	jpg、jpeg、png、bmp、gif、tif、tiff
音視頻	mp3、mp4、avi、wav
辦公文檔	pdf、doc、docx、ppt、pptx、xls、xlsx