MaxCompute:Python 3 UDAF

MaxCompute Studio を使用して、Python 3 でユーザー定義集計関数 (UDAF) のコードを作成できます。コードには、次の情報を含める必要があります。

• モジュールのインポート：必須。

  少なくとも from odps.udf import annotate と from odps.udf import BaseUDAF をインポートする必要があります。from odps.udf import annotate 文は、MaxCompute がコードで定義された関数シグネチャを認識できるようにする関数シグネチャモジュールをインポートします。from odps.udf import BaseUDAF は、Python UDAF の基底クラスをインポートします。派生クラスでは、iterate、merge、terminate などのメソッドを実装する必要があります。

  UDAF コードがファイルリソースまたはテーブルリソースを参照する必要がある場合は、ファイルリソースには from odps.distcache import get_cache_file を、テーブルリソースには from odps.distcache import get_cache_table を含めます。

• 関数シグネチャ：必須。

  フォーマットは @annotate(<signature>) です。signature は、関数の入力パラメーターと戻り値のデータ型を定義します。関数シグネチャの詳細については、「関数シグネチャとデータ型」をご参照ください。

• カスタム Python クラス (派生クラス)：必須。

  このクラスは UDAF コードの組織単位です。ビジネスロジックを実装する変数とメソッドを定義します。コード内でビルトインのサードパーティライブラリ、ファイル、またはテーブルリソースを参照することもできます。詳細については、「サードパーティライブラリ」または「リソースの参照」をご参照ください。

• Python クラスメソッドの実装：必須。

  Python クラスの実装には、次のメソッドが含まれます。必要に応じてメソッドを実装できます。

  メソッド定義	説明
  BaseUDAF.new_buffer()	集計関数の中間値用のバッファーを返します。buffer は、LIST や DICT などの Marshal オブジェクトである必要があります。buffer のサイズはデータ量に応じて増加してはいけません。極端な場合、オブジェクトシリアル化後の buffer のサイズは 2 MB を超えてはなりません。
  BaseUDAF.iterate(buffer[, args, ...])	args を中間値 buffer に集計します。
  BaseUDAF.merge(buffer, pbuffer)	中間値 buffer と pbuffer をマージし、結果を buffer に格納します。
  BaseUDAF.terminate(buffer)	buffer を MaxCompute SQL の基本データ型に変換します。

次のコードは UDAF の例です。

# 関数シグネチャモジュールと基底クラスをインポートします。
from odps.udf import annotate
from odps.udf import BaseUDAF
# 関数シグネチャ。
@annotate('double->double')
# カスタム Python クラス。
class Average(BaseUDAF):
# Python クラスのメソッドを実装します。
    def new_buffer(self):
        return [0, 0]
    def iterate(self, buffer, number):
        if number is not None:
            buffer[0] += number
            buffer[1] += 1
    def merge(self, buffer, pbuffer):
        buffer[0] += pbuffer[0]
        buffer[1] += pbuffer[1]
    def terminate(self, buffer):
        if buffer[1] == 0:
            return 0.0
        return buffer[0] / buffer[1]

Python Software Foundation はまもなく Python 2 の保守を終了します。プロジェクトの種類に基づいてプロジェクトを移行することを推奨します。

• 新規プロジェクト：これは、新規の MaxCompute プロジェクト、または初めて Python UDAF を作成する MaxCompute プロジェクトに適用されます。すべての Python UDAF を Python 3 で作成することを推奨します。

• 既存のプロジェクト：これは、多数の既存の Python 2 UDAF を持つ MaxCompute プロジェクトに適用されます。Python 3 の有効化は慎重に行ってください。すべての Python 2 UDAF を段階的に Python 3 に移行する予定の場合は、次のメソッドを使用します。

  • 新しいジョブと新しい UDAF：Python 3 で作成し、セッションレベルで Python 3 を有効にします。Python 3 を有効にする方法の詳細については、「Python 3 の有効化」をご参照ください。

  • Python 2 UDAF：Python 2 と Python 3 の両方と互換性があるように Python 2 UDAF を書き換えます。コードの書き換えの詳細については、「Porting Python 2 Code to Python 3」をご参照ください。

    説明

    パブリック UDAF を作成し、複数の MaxCompute プロジェクトに使用権限を付与する場合は、UDAF を Python 2 と Python 3 の両方と互換性があるようにすることを推奨します。

@annotate(<signature>)

'arg_type_list -> type'

• arg_type_list：入力パラメーターのデータ型を表します。複数の入力パラメーターをコンマ (,) で区切って指定できます。サポートされているデータ型は、BIGINT、STRING、DOUBLE、BOOLEAN、DATETIME、DECIMAL、FLOAT、BINARY、DATE、DECIMAL(precision,scale)、CHAR、VARCHAR、複雑なデータ型 (ARRAY、MAP、STRUCT)、およびネストされた複雑なデータ型です。

  arg_type_list は、アスタリスク (*) または空の文字列 ('') もサポートします。

  • arg_type_list がアスタリスク (*) の場合、関数が任意の数の入力パラメーターを受け入れることを示します。

  • arg_type_list が空の文字列 ('') の場合、関数に入力パラメーターがないことを示します。

  Resolve アノテーションの拡張構文の詳細については、「UDAF と UDTF の動的パラメーター」をご参照ください。

• type：戻り値のデータ型を表します。UDAF は 1 つの列のみを返します。サポートされているデータ型には、BIGINT、STRING、DOUBLE、BOOLEAN、DATETIME、DECIMAL、FLOAT、BINARY、DATE、DECIMAL(precision,scale)、複雑なデータ型 (ARRAY、MAP、STRUCT)、およびネストされた複雑なデータ型が含まれます。

開発フローに従って Python 3 UDAF を開発した後、MaxCompute SQL ステートメントでそれを呼び出すことができます。呼び出しメソッドは次のとおりです。

• MaxCompute プロジェクトで UDF を使用する：メソッドはビルトイン関数の使用方法と似ています。ビルトイン関数を使用するのと同じ方法でユーザー定義関数を使用できます。

• プロジェクト間で UDF を使用する：プロジェクト A でプロジェクト B の UDF を使用します。次のステートメントは例を示しています：select B:udf_in_other_project(arg0, arg1) as res from table_t;。プロジェクト間の共有の詳細については、「パッケージに基づくプロジェクト間のリソースアクセス」をご参照ください。