Mengembangkan UDF dalam Python 2 - MaxCompute

Versi Python 2 yang digunakan oleh MaxCompute adalah Python 2.7. Topik ini menjelaskan cara menulis fungsi yang ditentukan pengguna (UDF) dalam Python 2.

Struktur kode UDF

Anda dapat menggunakan MaxCompute Studio untuk menulis kode UDF dalam Python 2. Kode UDF dapat mencakup informasi berikut:

Deklarasi Pengkodean: Opsional.
Format deklarasi adalah #coding:utf-8 atau # -*- coding: utf-8 -*-. Kedua format tersebut setara. Jika karakter Cina muncul dalam kode UDF yang ditulis dalam Python 2, kesalahan akan dikembalikan saat Anda menjalankan UDF. Untuk mengatasi masalah ini, tambahkan deklarasi pengkodean ke header kode.
Impor Modul: Diperlukan.
Kode UDF harus menyertakan from odps.udf import annotate, yang digunakan untuk mengimpor tanda tangan fungsi. Dengan cara ini, MaxCompute dapat mengidentifikasi tanda tangan fungsi yang didefinisikan dalam kode. Jika ingin mereferensikan file atau tabel dalam kode UDF, kode UDF harus menyertakan from odps.distcache import get_cache_file atau from odps.distcache import get_cache_table.
Tanda Tangan Fungsi: Diperlukan.
Tanda tangan fungsi dalam format @annotate(<signature>). Parameter signature digunakan untuk mendefinisikan tipe data parameter input dan nilai kembali dari UDF. Untuk informasi lebih lanjut tentang tanda tangan fungsi, lihat Tanda Tangan Fungsi dan Tipe Data.
Kelas Python Kustom: Diperlukan.
Kelas Python kustom adalah unit organisasi kode UDF. Kelas ini mendefinisikan variabel dan metode yang digunakan untuk memenuhi kebutuhan bisnis Anda. Dalam kode UDF, Anda juga dapat mereferensikan pustaka pihak ketiga yang diinstal di MaxCompute atau mereferensikan file atau tabel. Untuk informasi lebih lanjut, lihat Pustaka Pihak Ketiga atau Referensi Sumber Daya.
evaluate Metode: Diperlukan.
Metode evaluate terkandung dalam kelas Python kustom. Metode ini mendefinisikan parameter input dan nilai kembali dari UDF. Setiap kelas Python hanya dapat berisi satu metode evaluate.

Contoh Kode:

#coding:utf-8
# Mengimpor tanda tangan fungsi.
from odps.udf import annotate
# Tanda tangan fungsi.
@annotate("bigint,bigint->bigint")
# Kelas Python kustom.
class MyPlus(object):
# Metode evaluate.
   def evaluate(self, arg0, arg1):
       if None in (arg0, arg1):
           return None
       return arg0 + arg1

Batasan

MaxCompute memungkinkan Anda menulis UDF Python 2 dalam Python 2.7 dan menjalankan kode UDF dalam lingkungan sandbox. Dalam lingkungan ini, operasi berikut dilarang:

Membaca dan menulis data ke file lokal.
Memulai subproses.
Memulai thread.
Mengaktifkan komunikasi soket.
Menggunakan sistem lain untuk memanggil UDF Python 2.

Karena batasan ini, kode yang Anda unggah harus ditulis menggunakan pustaka standar Python. Jika modul atau modul ekstensi C dalam pustaka standar Python terlibat dalam operasi sebelumnya, modul ini tidak dapat digunakan. Perhatikan poin-poin berikut tentang modul dalam pustaka standar Python:

Semua modul yang diimplementasikan berdasarkan pustaka standar Python dan tidak bergantung pada modul ekstensi tersedia.
Modul ekstensi C berikut tersedia:
- array dan audioop
- binascii dan bisect
- cmath, _codecs_cn, _codecs_hk, _codecs_iso2022, _codecs_jp, _codecs_kr, _codecs_tw, _collections, dan cStringIO
- datetime
- _functools dan future_builtins
- _heapq dan _hashlib
- itertools
- _json
- _locale dan _lsprof
- math, _md5, dan _multibytecodec
- operator
- _random
- _sha256, _sha512, _sha, _struct, dan strop
- time
- unicodedata
- _weakref
- cPickle
Saat menjalankan kode UDF dalam lingkungan sandbox, ukuran maksimum data yang dapat ditulis ke output standar (sys.stdout) atau output kesalahan standar (sys.stderr) adalah 20 KB. Jika ukurannya melebihi 20 KB, karakter tambahan diabaikan.

Pustaka pihak ketiga

Pustaka pihak ketiga, seperti NumPy, diinstal dalam lingkungan Python 2 MaxCompute sebagai pelengkap pustaka standar.

Catatan

Penggunaan pustaka pihak ketiga tunduk pada beberapa batasan. Misalnya, saat menggunakan pustaka pihak ketiga, Anda tidak diizinkan mengakses data lokal dan hanya dapat menggunakan sumber daya I/O jaringan yang terbatas. API terkait dalam pustaka pihak ketiga dinonaktifkan.

Tanda tangan fungsi dan tipe data

Format Tanda Tangan Fungsi:

@annotate(<signature>)

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

'arg_type_list -> type'

Deskripsi Parameter:

arg_type_list: Menentukan tipe data parameter input. Jika beberapa parameter input digunakan, tipe datanya dipisahkan oleh koma (,). Tipe data berikut didukung: BIGINT, STRING, DOUBLE, BOOLEAN, DATETIME, DECIMAL, FLOAT, BINARY, DATE, DECIMAL(presisi,skala), CHAR, dan VARCHAR. Tipe data kompleks, seperti ARRAY, MAP, dan STRUCT, serta tipe data kompleks bersarang juga didukung.
arg_type_list dapat direpresentasikan oleh asterisk (*) atau dibiarkan kosong ('').
- Jika arg_type_list direpresentasikan oleh asterisk (*), jumlah parameter input acak diizinkan.
- Jika arg_type_list dibiarkan kosong (''), tidak ada parameter input yang digunakan.
type: Menentukan tipe data nilai kembali. Untuk UDF, 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.

Catatan

Saat menulis kode UDF, Anda dapat memilih tipe data berdasarkan edisi tipe data MaxCompute yang digunakan oleh proyek MaxCompute Anda. Untuk informasi lebih lanjut tentang edisi tipe data MaxCompute dan tipe data yang didukung dalam setiap edisi, lihat Edisi Tipe Data.

Tabel berikut memberikan contoh tanda tangan fungsi yang valid.

Tanda tangan fungsi	Deskripsi
`'bigint,double->string'`	Tipe data parameter input adalah BIGINT dan DOUBLE dan tipe data nilai kembali adalah STRING.
`'*->string'`	Jumlah parameter input acak digunakan dan tipe data nilai kembali adalah STRING.
`'->double'`	Tidak ada parameter input yang digunakan dan tipe data nilai kembali adalah DOUBLE.
`'array<bigint>->struct<x:string, y:int>'`	Tipe data parameter input adalah ARRAY<BIGINT> dan tipe data nilai kembali adalah STRUCT<x:STRING, y:INT>.
`'->map<bigint, string>'`	Tidak ada parameter input yang digunakan dan tipe data nilai kembali adalah MAP<BIGINT, STRING>.

Tabel berikut menjelaskan pemetaan antara tipe data yang didukung dalam SQL MaxCompute dan tipe data Python 2. Anda harus menulis UDF Python berdasarkan pemetaan untuk memastikan konsistensi tipe data.

Tipe data SQL MaxCompute	Tipe data Python 2
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

Tipe DATETIME yang didukung dalam SQL MaxCompute dipetakan ke tipe data INT Python. Nilai tipe INT mengikuti format UNIX, yaitu jumlah milidetik yang telah berlalu sejak 00:00:00 Kamis, 1 Januari 1970. Anda dapat memproses data tipe DATETIME menggunakan modul DATETIME dalam pustaka standar Python.
Parameter silent ditambahkan ke odps.udf.int(value). Jika parameter silent disetel ke True dan tipe data value tidak dapat dikonversi menjadi tipe INT, None dikembalikan, dan tidak ada kesalahan yang dikembalikan.
NULL dalam SQL MaxCompute dipetakan ke None dalam Python 2.

Referensi sumber daya

Anda dapat mereferensikan file atau tabel dalam kode UDF Python 2 menggunakan modul odps.distcache.

odps.distcache.get_cache_file(resource_name): Mengembalikan konten file tertentu.
- resource_name adalah string yang menentukan nama file yang ada dalam proyek MaxCompute Anda. Jika nama file tidak valid atau file tidak ada, kesalahan dikembalikan.
  Catatan
  Untuk mereferensikan file dalam kode UDF, Anda harus mendeklarasikan file saat membuat UDF. Jika tidak, kesalahan dikembalikan saat Anda memanggil UDF.
- Nilai kembali adalah objek mirip file. Jika objek ini tidak lagi digunakan, Anda harus memanggil metode close untuk melepaskan file yang terbuka.
Kode berikut menunjukkan cara mereferensikan file.
```
from odps.udf import annotate
from odps.distcache import get_cache_file
@annotate('bigint->string')
class DistCacheExample(object):
def __init__(self):
    cache_file = get_cache_file('test_distcache.txt')
    kv = {}
    for line in cache_file:
        line = line.strip()
        if not line:
            continue
        k, v = line.split()
        kv[int(k)] = v
    cache_file.close()
    self.kv = kv
def evaluate(self, arg):
    return self.kv.get(arg)
```
odps.distcache.get_cache_table(resource_name): Mengembalikan konten tabel tertentu.
- resource_name adalah string yang menentukan nama tabel yang ada dalam proyek MaxCompute Anda. Jika nama tabel tidak valid atau tabel tidak ada, kesalahan dikembalikan.
- Nilai kembali adalah tipe data GENERATOR. Pemanggil melintasi tabel untuk mendapatkan konten tabel. Rekaman tipe ARRAY diperoleh setiap kali pemanggil melintasi tabel.
Kode berikut menunjukkan cara mereferensikan tabel.
```
from odps.udf import annotate
from odps.distcache import get_cache_table
@annotate('->string')
class DistCacheTableExample(object):
    def __init__(self):
        self.records = list(get_cache_table('udf_test'))
        self.counter = 0
        self.ln = len(self.records)
    def evaluate(self):
        if self.counter > self.ln - 1:
            return None
        ret = self.records[self.counter]
        self.counter += 1
        return str(ret)
```

Proses pengembangan

Saat mengembangkan UDF, Anda harus melakukan persiapan, menulis kode UDF, mengunggah program Python, membuat UDF, men-debug UDF, dan memanggil UDF. MaxCompute memungkinkan Anda menggunakan beberapa alat untuk mengembangkan UDF, seperti MaxCompute Studio, DataWorks, dan klien MaxCompute (odpscmd).

Proses menggunakan berbagai alat untuk mengembangkan UDF dalam Python 2 sama dengan proses mengembangkan UDF dalam Python 3. Untuk informasi lebih lanjut tentang proses pengembangan dan contoh bagaimana mengembangkan UDF dalam Python, lihat Proses Pengembangan.
Untuk informasi lebih lanjut tentang cara menggunakan MaxCompute Studio untuk mengembangkan dan memanggil UDF dalam Python 2, lihat Mengembangkan UDF Python.

Catatan penggunaan

Setelah mengembangkan UDF Python 2, Anda dapat menggunakan SQL MaxCompute untuk memanggil UDF ini. Anda dapat memanggil UDF Python 2 menggunakan salah satu metode berikut:

Gunakan UDF dalam proyek MaxCompute: Metodenya mirip dengan menggunakan fungsi bawaan.
Gunakan UDF lintas proyek: Gunakan UDF Proyek B dalam 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.