MaxCompute：Python 3 UDAF

Anda dapat menggunakan MaxCompute Studio untuk menulis kode UDAF dalam Python 3. Kode UDAF harus mencakup informasi berikut:

• Impor modul: wajib.

  Kode UDAF harus mencakup setidaknya from odps.udf import annotate dan from odps.udf import BaseUDAF. from odps.udf import annotate digunakan untuk mengimpor modul tanda tangan fungsi, sehingga MaxCompute dapat mengidentifikasi tanda tangan fungsi yang didefinisikan dalam kode. from odps.udf import BaseUDAF adalah kelas dasar untuk UDAF Python. Anda harus menggunakan kelas ini untuk mengimplementasikan metode seperti iterate, merge, atau terminate di kelas turunan.

  Jika Anda ingin merujuk file atau sumber daya tabel dalam kode UDAF, kode tersebut harus mencakup from odps.distcache import get_cache_file atau from odps.distcache import get_cache_table.

• Tanda tangan fungsi: wajib.

  Tanda tangan fungsi berada dalam format @annotate(<signature>). Parameter signature digunakan untuk mendefinisikan tipe data parameter input dan nilai balikan dari UDF. Untuk informasi lebih lanjut tentang tanda tangan fungsi, lihat Tanda Tangan Fungsi dan Tipe Data.

• Kelas Python kustom (kelas turunan): wajib.

  Kelas Java kustom adalah unit organisasi dalam kode UDAF. Kelas ini mendefinisikan variabel dan metode yang digunakan untuk memenuhi kebutuhan bisnis Anda. Dalam kode UDF, Anda dapat mereferensikan pustaka pihak ketiga yang diinstal di MaxCompute atau mereferensikan file atau tabel. Untuk informasi lebih lanjut, lihat Pustaka pihak ketiga atau Sumber referensi.

• Metode untuk mengimplementasikan kelas Python: wajib.

  Tabel berikut menjelaskan empat metode yang dapat digunakan untuk mengimplementasikan kelas Python. Anda dapat memilih metode berdasarkan kebutuhan bisnis Anda.

  Metode	Deskripsi
  BaseUDAF.new_buffer()	Mengembalikan buffer nilai antara dari UDAF. buffer harus berupa objek yang dapat dimarshalkan, seperti LIST atau DICT, dan ukuran buffer tidak boleh bertambah dengan jumlah data. Dalam kasus ekstrem, ukuran buffer tidak boleh melebihi 2 MB setelah operasi marshaling.
  BaseUDAF.iterate(buffer[, args, ...])	Menggabungkan args ke dalam nilai antara buffer.
  BaseUDAF.merge(buffer, pbuffer)	Menyimpan hasil penggabungan dari pbuffer dan nilai antara buffer di dalam buffer.
  BaseUDAF.terminate(buffer)	Mengonversi buffer menjadi nilai dari tipe data dasar dalam SQL MaxCompute.

Contoh kode:

# Impor modul tanda tangan fungsi dan kelas dasar. 
from odps.udf import annotate
from odps.udf import BaseUDAF
# Tanda tangan fungsi. 
@annotate('double->double')
# Kelas Python kustom. 
class Average(BaseUDAF):
# Metode yang digunakan untuk mengimplementasikan kelas Python kustom. 
    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]

Yayasan Perangkat Lunak Python mengumumkan EOL untuk Python 2. Oleh karena itu, kami merekomendasikan agar Anda memindahkan UDAF Python 2. Metode yang digunakan untuk memindahkan UDAF Python 2 bervariasi berdasarkan jenis proyek MaxCompute.

• Proyek baru: Jika proyek Anda adalah proyek MaxCompute baru atau jika ini pertama kalinya Anda menggunakan Python untuk menulis UDAF untuk proyek MaxCompute, kami merekomendasikan agar Anda menggunakan Python 3 untuk menulis semua UDAF Python.
• Proyek yang sudah ada: Jika proyek Anda adalah proyek yang sudah ada untuk mana sejumlah besar UDAF Python 2 telah dibuat, berhati-hatilah saat Anda mengaktifkan Python 3. Jika Anda berencana untuk secara bertahap mengganti UDAF Python 2 dengan UDAF Python 3, gunakan salah satu metode berikut:
  • Gunakan Python 3 untuk menulis UDAF baru dan aktifkan Python 3 untuk pekerjaan baru di tingkat sesi. Untuk informasi lebih lanjut tentang cara mengaktifkan Python 3, lihat Aktifkan Python 3.
  • Tulis ulang UDAF Python 2 agar kompatibel dengan Python 2 dan Python 3. Untuk informasi lebih lanjut tentang cara menulis ulang UDAF Python 2, lihat Memindahkan Kode Python 2 ke Python 3.
    Catatan Jika Anda ingin menulis UDAF publik yang dapat dibagikan di antara beberapa proyek, kami merekomendasikan agar UDAF tersebut kompatibel dengan Python 2 dan Python 3.

Format tanda tangan fungsi:

@annotate(<signature>)

Parameter signature adalah string yang menentukan tipe data parameter input dan nilai balikan. Saat Anda menjalankan UDAF, tipe data parameter input dan nilai balikan UDAF harus konsisten dengan tipe data yang ditentukan dalam tanda tangan fungsi. Konsistensi tipe data diperiksa selama penguraian semantik. Jika tipe data tidak konsisten, kesalahan akan dikembalikan. Format tanda tangan fungsi:

'arg_type_list -> type'

• arg_type_list: menentukan tipe data parameter input. Jika beberapa parameter input digunakan, tentukan beberapa tipe data dan pisahkan dengan koma (,). Tipe data berikut didukung: BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(presisi,skala), CHAR, VARCHAR, tipe data kompleks (ARRAY, MAP, dan STRUCT), dan tipe data kompleks bersarang.

  arg_type_list dapat direpresentasikan oleh asterisk (*) atau dibiarkan kosong ('').

  • Jika arg_type_list direpresentasikan oleh asterisk (*), jumlah parameter input acak diperbolehkan.

  • Jika arg_type_list dibiarkan kosong (''), tidak ada parameter input yang digunakan.

  Untuk informasi lebih lanjut tentang ekstensi sintaksis anotasi @Resolve, lihat Parameter Dinamis UDAF dan UDTF.

• type menentukan tipe data nilai balikan. Untuk UDAF, hanya satu kolom nilai yang dikembalikan. Tipe data berikut didukung: BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, dan DECIMAL(presisi, skala). Tipe data kompleks, seperti ARRAY, MAP, dan STRUCT, serta tipe data kompleks bersarang juga didukung.

Setelah Anda mengembangkan UDAF Python 3 dengan mengikuti petunjuk dalam Proses Pengembangan, Anda dapat menggunakan SQL MaxCompute untuk memanggil UDAF ini. Langkah-langkah berikut menjelaskan cara memanggil UDAF Python 3:

• Gunakan UDF dalam proyek MaxCompute: Metodenya serupa dengan penggunaan fungsi bawaan.

• Gunakan UDF lintas proyek: Gunakan UDF Proyek B di Proyek A. Pernyataan berikut menunjukkan contoh: select B:udf_in_other_project(arg0, arg1) as res from table_t;. Untuk informasi lebih lanjut tentang berbagi lintas proyek, lihat Akses Sumber Daya Lintas Proyek Berbasis Paket.

Untuk informasi lebih lanjut tentang format tanda tangan fungsi UDAF Python, lihat Tanda Tangan Fungsi dan Tipe Data.

• Anda dapat menggunakan asterisk (*) dalam daftar parameter untuk menunjukkan bahwa parameter input dapat memiliki panjang dan tipe apa pun. Sebagai contoh, @annotate('double,*->string') menunjukkan daftar parameter di mana parameter pertama adalah tipe data DOUBLE dan diikuti oleh parameter dengan panjang dan tipe apa pun. Dalam hal ini, Anda harus menyusun kode untuk menghitung jumlah dan tipe parameter input, dan mengelolanya berdasarkan fungsi printf dalam bahasa pemrograman C.
  Catatan Asterisk (*) dalam nilai balikan menunjukkan arti yang berbeda.
• Asterisk (*) dapat digunakan dalam nilai balikan UDTF untuk menunjukkan bahwa sejumlah nilai tipe data STRING dapat dikembalikan. Jumlah nilai balikan didasarkan pada jumlah alias yang dikonfigurasi saat fungsi dipanggil. Sebagai contoh, metode panggilan @annotate("bigint,string->double,*") adalah UDTF(x, y) as (a, b, c). Dalam contoh ini, alias a, b, dan c dikonfigurasi setelah as. Editor mengidentifikasi bahwa a adalah tipe DOUBLE dan b dan c adalah tipe STRING. Tipe data nilai balikan di kolom pertama yang dikembalikan dalam anotasi Resolve diberikan. Tiga nilai balikan disediakan dalam contoh ini. Oleh karena itu, metode forward yang dipanggil oleh UDTF harus forward array dengan tiga elemen. Jika tidak, kesalahan akan dikembalikan.
  Catatan Namun, kesalahan tidak dikembalikan selama kompilasi. Oleh karena itu, pemanggil UDTF harus mengonfigurasi jumlah alias dalam SQL berdasarkan aturan yang didefinisikan dalam UDTF. Jumlah nilai balikan dari fungsi agregat tetap 1. Oleh karena itu, aturan ini tidak berpengaruh pada UDAF.

from odps.udf import annotate
from odps.udf import BaseUDAF
@annotate('bigint,*->string')
class MultiColSum(BaseUDAF):
    def new_buffer(self):
        return [0]
    def iterate(self, buffer, *args):
        for arg in args:
            buffer[0] += int(arg)
    def merge(self, buffer, pbuffer):
        buffer[0] += pbuffer[0]
    def terminate(self, buffer):
        return str(buffer[0])

Jumlah nilai balikan UDAF hanya dapat ditetapkan menjadi satu. Dalam contoh sebelumnya, nilai balikan adalah jumlah nilai dari beberapa parameter input dan jumlah nilai dalam beberapa baris. Contoh pernyataan:

-- Hitung jumlah nilai dari beberapa parameter input.
SELECT my_multi_col_sum(a,b,c,d,e) from values (1,"2","3","4","5"), (6,"7","8","9","10") t(a,b,c,d,e);
-- Nilai balikannya adalah 55.