All Products
Search

This Product

    MaxCompute:Python 2 UDAF

    Document Center

    MaxCompute:Python 2 UDAF

    Last Updated:Mar 27, 2026

    Fungsi agregat yang didefinisikan pengguna (UDAF) bekerja seperti fungsi agregat bawaan, misalnya SUM atau AVG, tetapi Anda yang menentukan logika agregasinya. MaxCompute menjalankan UDAF Python 2 menggunakan Python 2.7.

    Gunakan MaxCompute Studio untuk menulis dan mengunggah kode UDAF.

    Struktur kode

    Berkas UDAF Python 2 terdiri dari lima komponen:

    Component Required Description
    Deklarasi encoding Opsional Tambahkan #coding:utf-8 atau # -*- coding: utf-8 -*- di bagian atas berkas jika kode berisi karakter Tionghoa. Tanpa deklarasi ini, UDAF akan mengembalikan error saat waktu proses.
    Impor modul Wajib Impor from odps.udf import annotate dan from odps.udf import BaseUDAF. Untuk mereferensikan resource file atau tabel, impor juga from odps.distcache import get_cache_file atau from odps.distcache import get_cache_table.
    Signature fungsi Wajib Deklarasikan tipe data input dan return menggunakan @annotate(<signature>). MaxCompute memvalidasi konsistensi tipe selama penguraian semantik.
    Kelas Python kustom Wajib Perluas BaseUDAF untuk menentukan logika agregasi.
    Metode Wajib Implementasikan keempat metode yang dijelaskan di Metode.

    Metode

    Keempat metode wajib diimplementasikan dalam kelas yang memperluas BaseUDAF.

    Method Required Description
    BaseUDAF.new_buffer() Wajib Mengembalikan nilai antara buffer. buffer harus berupa objek yang dapat dimarshal (marshallable), seperti LIST atau DICT. Ukurannya tidak boleh bertambah seiring dengan jumlah data masukan. Setelah dimarshal, ukuran buffer tidak boleh melebihi 2 MB.
    BaseUDAF.iterate(buffer[, args, ...]) Wajib Mengagregasi args dari setiap baris input ke dalam buffer.
    BaseUDAF.merge(buffer, pbuffer) Wajib Menggabungkan pbuffer ke dalam buffer. MaxCompute memanggil metode ini saat menggabungkan hasil parsial dari berbagai worker.
    BaseUDAF.terminate(buffer) Wajib Mengonversi buffer akhir menjadi nilai tipe data dasar MaxCompute SQL dan mengembalikannya.

    Contoh: menghitung rata-rata

    UDAF berikut menghitung rata-rata kolom DOUBLE dan mengembalikan hasil bertipe DOUBLE.

    #coding:utf-8
from odps.udf import annotate
from odps.udf import BaseUDAF

@annotate('double->double')
class Average(BaseUDAF):

    def new_buffer(self):
        # Buffer menyimpan [sum, count] sebagai list
        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]

    Setelah mengunggah dan mendaftarkan UDAF (misalnya sebagai my_avg), panggil fungsi tersebut dalam MaxCompute SQL sebagaimana memanggil fungsi agregat bawaan:

    -- Menghitung skor rata-rata per kategori
SELECT category, my_avg(score) AS avg_score
FROM my_table
GROUP BY category;

    Untuk pemanggilan lintas proyek, tambahkan awalan nama proyek pada fungsi:

    SELECT B:my_avg(score) AS avg_score FROM my_table;

    Untuk proses pengembangan dan pendaftaran lengkap, lihat Develop a Python UDF.

    Signature fungsi dan tipe data

    Format tanda tangan

    @annotate('<arg_type_list> -> <return_type>')

    • arg_type_list: daftar tipe input yang dipisahkan koma. Gunakan * untuk jumlah input apa pun, atau kosongkan jika tidak ada input.

    • return_type: satu tipe return. UDAF selalu mengembalikan satu kolom.

    Tipe input yang didukung: BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(precision,scale), CHAR, VARCHAR, ARRAY, MAP, STRUCT, dan tipe kompleks bersarang.

    Tipe return yang didukung: BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(precision,scale), ARRAY, MAP, STRUCT, dan tipe kompleks bersarang.

    Catatan Tipe data yang tersedia bergantung pada edisi tipe data proyek MaxCompute Anda. Untuk detailnya, lihat Data type editions.

    Contoh:

    Signature Meaning
    @annotate('bigint,double->string') Menerima input BIGINT dan DOUBLE, mengembalikan STRING
    @annotate('*->string') Menerima sejumlah input apa pun, mengembalikan STRING
    @annotate('->double') Tidak menerima input, mengembalikan DOUBLE
    @annotate('array<bigint>->struct<x:string, y:int>') Menerima ARRAY<BIGINT>, mengembalikan STRUCT<x:STRING, y:INT>

    Pemetaan tipe data

    Tulis logika UDAF menggunakan tipe Python 2 yang sesuai untuk setiap tipe MaxCompute SQL.

    MaxCompute SQL type Python 2 type
    BIGINT INT
    STRING STR
    DOUBLE FLOAT
    BOOLEAN BOOL
    DATETIME INT
    FLOAT FLOAT
    CHAR STR
    VARCHAR STR
    BINARY BYTEARRAY
    DATE INT
    DECIMAL DECIMAL.DECIMAL
    ARRAY LIST
    MAP DICT
    STRUCT COLLECTIONS.NAMEDTUPLE
    Catatan
    • DATETIME dipetakan ke INT mengikuti format Stempel waktu UNIX: milidetik yang telah berlalu sejak 1970-01-01 00:00:00 UTC. Gunakan modul datetime Python untuk memproses nilai DATETIME.
    • NULL dalam MaxCompute SQL dipetakan ke None dalam Python 2.
    • odps.udf.int(value, silent=True) mengembalikan None alih-alih memunculkan error ketika value tidak dapat dikonversi ke INT.

    Batasan

    MaxCompute menjalankan kode UDAF dalam lingkungan sandbox. Operasi berikut tidak diizinkan:

    • Membaca dari atau menulis ke file lokal

    • Menjalankan subprocess

    • Menjalankan thread

    • Menggunakan komunikasi socket

    • Memanggil user-defined function (UDF) Python 2 dari sistem lain

    Unggah hanya kode yang menggunakan library standar Python. Jika modul library standar atau modul ekstensi C melakukan salah satu operasi di atas, modul tersebut tidak dapat digunakan.

    Modul yang tersedia:

    • Semua modul library standar Python murni (tanpa dependensi ekstensi C) tersedia.

    • Modul ekstensi C berikut tersedia: array, audioop, binascii, bisect, cmath, _codecs_cn, _codecs_hk, _codecs_iso2022, _codecs_jp, _codecs_kr, _codecs_tw, _collections, cStringIO, datetime, _functools, future_builtins, _heapq, _hashlib, itertools, _json, _locale, _lsprof, math, _md5, _multibytecodec, operator, _random, _sha256, _sha512, _sha, _struct, strop, time, unicodedata, _weakref, cPickle.

    Batas output: Menulis ke sys.stdout atau sys.stderr dibatasi hingga 20 KB. Karakter yang melebihi batas tersebut akan diabaikan tanpa pemberitahuan.

    Library pihak ketiga

    Library pihak ketiga, seperti NumPy, telah dipra-instal di lingkungan Python 2 MaxCompute sebagai pelengkap library standar.

    Catatan Library pihak ketiga beroperasi di bawah batasan sandbox yang sama: akses data lokal diblokir dan I/O jaringan dibatasi. API terkait dalam library pihak ketiga dinonaktifkan.

    Resource referensi

    Akses file dan tabel yang didaftarkan sebagai resource MaxCompute dari dalam kode UDAF menggunakan modul odps.distcache.

    odps.distcache.get_cache_file(resource_name)

    Mengembalikan objek mirip file untuk resource file yang ditentukan.

    • resource_name harus merupakan nama resource file yang sudah ada di proyek MaxCompute Anda. Nama yang tidak valid atau file yang tidak ada akan menyebabkan error.

    • Deklarasikan file tersebut saat membuat UDAF. Pemanggilan tanpa mendeklarasikan resource akan menghasilkan error.

    • Panggil close() pada objek yang dikembalikan setelah selesai menggunakannya untuk melepaskan resource.

    odps.distcache.get_cache_table(resource_name)

    Mengembalikan generator yang menghasilkan satu catatan bertipe ARRAY per iterasi untuk resource tabel yang ditentukan.

    • resource_name harus merupakan nama resource tabel yang sudah ada di proyek MaxCompute Anda. Nama yang tidak valid atau tabel yang tidak ada akan menyebabkan error.

    Untuk contoh penggunaan, lihat Reference resources (Python 2 UDFs) dan Reference resources (Python 2 UDTFs).

    Langkah selanjutnya