すべてのプロダクト
Search
ドキュメントセンター

MaxCompute:メタデータ処理 (Java)

最終更新日:Sep 19, 2026

MaxCompute オブジェクトテーブルは、OSS に保存されている非構造化データのメタデータを抽出し、ファイル形式を特定するための一般的な Java UDF を提供しています。

AI データ処理において、画像、音声、動画、PDF、Office ドキュメントなどの非構造化データからメタデータを抽出することは、オブジェクトテーブルの典型的なユースケースです。OSS に保存された非構造化データが、モデルトレーニング、コンテンツ理解、または検索拡張生成 (RAG) などのパイプラインに入る前に、ファイルのメタデータをバッチで抽出する必要があることがよくあります。例:

  • 画像から寸法、形式、EXIF 情報を抽出する。

  • 音声ファイルや動画ファイルから、再生時間、サンプルレート、エンコーディング形式、キーフレームを抽出する。

  • PDF や Word ドキュメントからページ数、作成者、作成日時を解析する。

MaxCompute は、SQL 内で直接オブジェクトテーブルファイルに対してメタデータ抽出と軽量な前処理を実行するために、以下の Java UDF を提供しています。抽出された結果を使用して、構造化されたメタデータテーブルの構築、データセットのフィルタリングやサンプリング、および特徴量エンジニアリングやベクトル化などの下流タスクにフィードできます。

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

    Office ドキュメント

    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)
  • パラメーター

    パラメーター

    タイプ

    デフォルト

    説明

    metadataKeyDelimiter

    String

    "."

    階層的なメタデータキー名のデリミタ。

    画像ファイルの場合、メタデータディレクトリとタグの間のデリミタとして使用されます。例:

    • デフォルト: "EXIF.DateTimeOriginal"

    • カスタム/: "EXIF/DateTimeOriginal"

    パスワード

    String

    null

    暗号化された PDF ファイルのパスワードです。この機能は pdf 形式にのみ適用されます。暗号化された Office ドキュメントなど、その他の暗号化されたファイルはサポートされていません。

    parseFailPolicy

    String

    "OUTPUT_NULL"

    解析失敗時の処理ポリシー。有効な値は次のとおりです:

    • OUTPUT_DEFAULT:デフォルト値である null を警告なしで返します。

    • OUTPUT_NULL:警告なしで null を返します。

    • WARN_AND_NULL:警告ログを出力し、null を返します。

    • THROW_EXCEPTION:例外をスローしてプロセスを中断します。

    metadataKeyExclusionRegex

    String

    null

    メタデータキーの正規表現フィルター。キーが正規表現に一致するメタデータ項目を削除します。複数のパターンはカンマで区切ります。例:

    • "Photoshop.*" (キーが Photoshop で始まるエントリを削除)

    • ".*Path Info.*" (キーに部分文字列 Path Info を含むエントリを削除する)

GetFileFormat

GetFileFormat は、json、csv、orc、parquet などのファイルの詳細フォーマットを抽出します。戻り値は String 型です。

  • シグネチャ

    • 使用法 1:ファイル名から形式を抽出

      evaluate(String fileName, String parseFailPolicy)
    • 使用法 2:バイナリデータとファイル名から形式を抽出

      evaluate(Binary data, String fileName, String parseFailPolicy)
  • パラメーター

    parseFailPolicy: パース失敗を処理するためのポリシーです。データ型は文字列です。デフォルト値は "OUTPUT_NULL" です。有効な値は次のとおりです。

    • OUTPUT_DEFAULT:デフォルト値である null を警告なしで返します。

    • OUTPUT_NULL:警告なしで null を返します。

    • WARN_AND_NULL:警告ログを出力し、null を返します。

    • THROW_EXCEPTION:例外をスローしてプロセスを中断します。

GetFileMediaType

GetFileMediaType は、IANA レジストリに基づいてファイルのトップレベルの MIME メディアタイプを検出します。戻り値の型は String です。

  • サポートされるメディアタイプ:

    • アプリケーション

    • audio

    • 例

    • フォント

    • ハプティクス

    • イメージ

    • メッセージ

    • モデル

    • `マルチパート`

    • テキスト

    • video

  • シグネチャ

    • 使用法 1:ファイル名からメディアタイプを検出

      evaluate(String fileName, String parseFailPolicy)
    • 使用法 2:バイナリデータとファイル名からメディアタイプを検出

      evaluate(Binary data, String fileName, String parseFailPolicy)
  • パラメーター

    parseFailPolicy: パース失敗を処理するためのポリシーです。データ型は文字列です。デフォルト値は "OUTPUT_NULL" です。有効な値は次のとおりです。

    • OUTPUT_DEFAULT:デフォルト値である null を警告なしで返します。

    • OUTPUT_NULL:警告なしで null を返します。

    • WARN_AND_NULL:警告ログを出力し、null を返します。

    • THROW_EXCEPTION:例外をスローしてプロセスを中断します。

GetFileContentType

GetFileContentType は、ファイルの完全な MIME コンテンツタイプ (Content-Type) を返します。戻り値の型は String です。

  • シグネチャ

    • 使用法 1:ファイル名からコンテンツタイプを検出

      evaluate(String fileName, String parseFailPolicy)
    • 使用法 2:バイナリデータとファイル名からコンテンツタイプを検出

      evaluate(Binary data, String fileName, String parseFailPolicy)
  • パラメーター

    parseFailPolicy: パース失敗を処理するためのポリシーです。データ型は文字列です。デフォルト値は "OUTPUT_NULL" です。有効な値は次のとおりです。

    • OUTPUT_DEFAULT:デフォルト値である null を警告なしで返します。

    • OUTPUT_NULL:警告なしで null を返します。

    • WARN_AND_NULL:警告ログを出力し、null を返します。

    • THROW_EXCEPTION:例外をスローしてプロセスを中断します。

GetFileName

GetFileName はファイルパスからファイル名を抽出します。戻り値の型は String です。

  • シグネチャ

    evaluate(String filePath, String parseFailPolicy)
  • パラメーター

    parseFailPolicy: パース失敗を処理するためのポリシーです。データ型は文字列です。デフォルト値は "OUTPUT_NULL" です。有効な値は次のとおりです。

    • OUTPUT_DEFAULT:デフォルト値である null を警告なしで返します。

    • OUTPUT_NULL:警告なしで null を返します。

    • WARN_AND_NULL:警告ログを出力し、null を返します。

    • THROW_EXCEPTION:例外をスローしてプロセスを中断します。

使用例

  1. データの準備

    OSS コンソールにログインし、データをアップロードします。この例では、次のテストデータを使用します:object_table_demo_files.zip。

  2. UDF JAR パッケージのアップロードと UDF の作成

    Java UDF JAR パッケージをダウンロードします: lakehouse-udf-1.0-SNAPSHOT.jar

    この例では odpscmd を使用します。JAR パッケージをアップロードする他の方法については、「Java UDF」をご参照ください。

    -- odpscmd 環境に入ります。
    SET odps.sql.allow.namespace.schema=true;
    SET odps.namespace.schema=true;
    SET odps.sql.type.system.odps2=true;
    
    -- オブジェクトテーブルを作成します。
    DROP TABLE IF EXISTS udf_demo;
    CREATE OBJECT TABLE udf_demo 
    WITH serdeproperties (
      'odps.properties.rolearn'='acs:ram::<uid>:role/<role_name>'
    ) 
    LOCATION 'oss://<endpoint>/<bucket>/path/to/files/'; -- アップロードしたファイルの OSS ロケーションに置き換えてください。
    -- オブジェクトテーブルのメタデータを更新します。
    ALTER TABLE udf_demo refresh metadata;
    
    -- UDF JAR パッケージをアップロードして関数を作成します。
    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';
  3. オブジェクトテーブルでの関数の使用

    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('udf_demo', key), -- バイナリ形式のファイルコンテンツ。
        get_file_format(key, 'OUTPUT_DEFAULT')  -- ファイルタイプ (pdf、mp3、avi、jpg など)。
      )
    from udf_demo;

よくある質問

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 など、他のリソースとの間でクラス競合を引き起こす可能性があります。

  • 解決策

    新しいスキーマを作成し、そこに UDF JAR パッケージをアップロードしてから、UDF を作成して使用します。それでも問題が解決しない場合は、関数を使用する前に新しいプロジェクトを作成してください。