All Products
Search

This Product

    MaxCompute:Java UDTFs

    Document Center

    MaxCompute:Java UDTFs

    Last Updated:Jul 02, 2025

    MaxCompute memungkinkan Anda menulis fungsi bernilai tabel yang ditentukan pengguna (UDTF) dalam Java. Hal ini membantu memproses tugas pemrosesan data kompleks secara efisien. Java UDTF dapat lebih memenuhi kebutuhan pemrosesan data spesifik dan meningkatkan efisiensi pengembangan serta kinerja pemrosesan berdasarkan karakteristik Java. Topik ini menjelaskan struktur kode, perhatian khusus, dan contoh-contoh UDTF.

    Struktur kode UDTF

    Anda dapat menggunakan Maven di IntelliJ IDEA atau MaxCompute Studio untuk menulis kode UDTF dalam Java. Kode UDTF dapat mencakup informasi berikut:

    • Paket Java: opsional.

      Anda dapat mengemas kelas-kelas Java yang didefinisikan ke dalam file JAR untuk digunakan di masa mendatang.

    • Kelas dasar UDTF: wajib.

      Kelas dasar UDTF berikut harus disertakan: com.aliyun.odps.udf.UDTF, com.aliyun.odps.udf.annotation.Resolve, dan com.aliyun.odps.udf.UDFException. com.aliyun.odps.udf.annotation.Resolve menentukan anotasi @Resolve, dan com.aliyun.odps.udf.UDFException menentukan metode yang digunakan untuk mengimplementasikan kelas Java. Jika Anda perlu menggunakan kelas UDTF lainnya atau tipe data kompleks, tambahkan kelas yang diperlukan dengan mengikuti petunjuk yang diberikan di Ikhtisar.

    • Kelas Java kustom: wajib.

      Kelas kustom adalah unit organisasi dari kode UDTF. Kelas ini mendefinisikan variabel dan metode yang digunakan untuk memenuhi kebutuhan bisnis Anda.

    • Anotasi @Resolve: wajib.

      Anotasi ini memiliki format @Resolve(<signature>). signature adalah tanda tangan fungsi yang mendefinisikan tipe data parameter input dan nilai balik UDTF. Anda tidak dapat memperoleh tanda tangan fungsi untuk UDTF dengan menggunakan fitur refleksi. Anda hanya dapat memperoleh tanda tangan fungsi dengan menggunakan anotasi @Resolve, seperti @Resolve("smallint->varchar(10)"). Untuk informasi lebih lanjut tentang anotasi @Resolve, lihat Anotasi @Resolve dalam topik ini.

    • Metode untuk mengimplementasikan kelas Java kustom: wajib.

      Tabel berikut menjelaskan metode yang dapat digunakan untuk mengimplementasikan kelas Java. Anda dapat memilih salah satu metode berdasarkan kebutuhan bisnis Anda.

      Metode

      Deskripsi

      public void setup(ExecutionContext ctx) throws UDFException

      Metode inisialisasi. Sebelum UDTF memproses data input, MaxCompute memanggil kode untuk perilaku inisialisasi yang ditentukan pengguna. setup dipanggil sekali untuk setiap pekerja.

      public void process(Object[] args) throws UDFException

      process dipanggil sekali untuk setiap rekaman SQL. Parameter dari process adalah parameter input UDTF yang ditentukan dalam pernyataan SQL. Parameter input dilewatkan dalam fungsi proses sebagai Object[], dan hasilnya dikembalikan dengan menggunakan fungsi forward. Anda harus memanggil fungsi forward dalam fungsi process untuk menentukan data keluaran.

      Catatan

      Kehilangan data mungkin terjadi jika Anda tidak menggunakan metode process atau close untuk memanggil fungsi forward. Lanjutkan dengan hati-hati. Misalnya, thread backend digunakan untuk menjalankan pemanggilan forward. Anda harus memastikan bahwa metode process tidak selesai sampai pemanggilan forward selesai, jika tidak, itu dapat menyebabkan kehilangan data.

      public void close() throws UDFException

      Metode untuk mengakhiri UDTF. Metode ini hanya dipanggil sekali, setelah rekaman terakhir diproses.

      Anda dapat memanggil fungsi forward untuk mengembalikan data. Satu rekaman dihasilkan setiap kali fungsi forward dipanggil. Saat Anda memanggil UDTF dalam pernyataan kueri SQL, Anda dapat menggunakan klausa AS untuk mengganti nama output dari fungsi forward.

      Anda dapat menggunakan tipe data Java atau tipe data writable Java untuk menulis Java UDTF. Untuk informasi lebih lanjut tentang pemetaan antara tipe data yang didukung oleh proyek MaxCompute, tipe data Java, dan tipe data writable Java, lihat Tipe Data.

    Contoh berikut menunjukkan kode UDTF.

    // Kemas kelas-kelas Java ke dalam file JAR bernama org.alidata.odps.udtf.examples.
package org.alidata.odps.udtf.examples;
// Kelas dasar UDTF.
import com.aliyun.odps.udf.UDTF;
import com.aliyun.odps.udf.UDTFCollector;
import com.aliyun.odps.udf.annotation.Resolve;
import com.aliyun.odps.udf.UDFException;
// Kelas Java kustom.
// Anotasi @Resolve.
@Resolve("string,bigint->string,bigint")
public class MyUDTF extends UDTF {     
     // Metode yang digunakan untuk mengimplementasikan kelas Java kustom.
     @Override
     public void process(Object[] args) throws UDFException {
         String a = (String) args[0];
         Long b = (Long) args[1];
         for (String t: a.split("\\s+")) {
         forward(t, b);
       }
     }
   }

    Batasan

    • Anda tidak dapat mengakses Internet dengan menggunakan fungsi yang ditentukan pengguna (UDF). Jika Anda ingin mengakses Internet dengan menggunakan UDF, isi formulir aplikasi koneksi jaringan berdasarkan kebutuhan bisnis Anda dan kirimkan aplikasi tersebut. Setelah aplikasi disetujui, tim dukungan teknis MaxCompute akan menghubungi Anda dan membantu Anda menetapkan koneksi jaringan. Untuk informasi lebih lanjut tentang cara mengisi formulir aplikasi koneksi jaringan, lihat Proses koneksi jaringan.
    • Jika Anda menggunakan UDTF dalam pernyataan SELECT, Anda tidak dapat menentukan kolom lain atau menggunakan ekspresi lain dalam pernyataan ini. Contoh kode sampel berikut menunjukkan pernyataan SQL yang salah.
      -- Pernyataan berisi UDTF dan kolom lain.
select value, user_udtf(key) as mycol ...
    • UDTF tidak dapat bersarang. Contoh kode sampel berikut menunjukkan pernyataan SQL yang salah.
      -- UDTF bernama user_udtf2 bersarang dalam UDTF bernama user_udtf1.
select user_udtf1(user_udtf2(key)) as mycol...;
    • UDTF tidak dapat digunakan dengan klausa GROUP BY, DISTRIBUTE BY, atau SORT BY dalam pernyataan SELECT yang sama. Contoh kode sampel berikut menunjukkan pernyataan SQL yang salah.
      -- UDTF digunakan bersama dengan klausa GROUP BY.
select user_udtf(key) as mycol ... group by mycol;

    Perhatian

    Saat Anda menulis Java UDTF, perhatikan poin-poin berikut:

    • Kami sarankan agar Anda tidak mengemas kelas-kelas yang memiliki nama sama tetapi logika berbeda ke dalam file JAR dari UDTF yang berbeda. Misalnya, file JAR UDTF 1 bernama udtf1.jar dan file JAR UDTF 2 bernama udtf2.jar. Kedua file tersebut berisi kelas bernama com.aliyun.UserFunction.class, tetapi kelas tersebut memiliki logika yang berbeda. Jika UDTF 1 dan UDTF 2 dipanggil dalam pernyataan SQL yang sama, MaxCompute memuat com.aliyun.UserFunction.class dari salah satu dari dua file tersebut. Akibatnya, UDTF tidak dapat berjalan sesuai harapan dan kesalahan kompilasi mungkin terjadi.

    • Tipe data parameter input atau nilai balik dalam Java UDTF adalah objek. Huruf pertama dari tipe data yang Anda tentukan dalam kode Java UDTF harus huruf besar, seperti String.

    • Nilai NULL dalam SQL MaxCompute direpresentasikan oleh NULL dalam Java. Tipe data primitif dalam Java tidak dapat merepresentasikan nilai NULL dalam SQL MaxCompute. Oleh karena itu, tipe data ini tidak dapat digunakan.

    Anotasi @Resolve

    Format anotasi @Resolve:

    @Resolve(<signature>)

    signature adalah string tanda tangan fungsi. Parameter ini digunakan untuk mengidentifikasi tipe data parameter input dan nilai balik. Saat UDTF dijalankan, parameter input dan nilai balik UDTF harus memiliki tipe data yang sama dengan yang ditentukan dalam tanda tangan fungsi. Konsistensi tipe data diperiksa selama penguraian semantik. Jika tipe data tidak konsisten, kesalahan akan dikembalikan. Tanda tangan dalam format berikut:

    'arg_type_list -> type_list'

    Deskripsi parameter:

    • type_list: menunjukkan tipe data nilai balik. UDTF dapat mengembalikan beberapa kolom. 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 bertingkat juga didukung.

    • 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 bertingkat.

      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.

    Tabel berikut memberikan contoh anotasi @Resolve.

    Anotasi @Resolve

    Deskripsi

    @Resolve('bigint,boolean->string,datetime')

    Tipe data parameter input adalah BIGINT dan BOOLEAN. Tipe data nilai balik adalah STRING dan DATETIME.

    @Resolve('*->string, datetime')

    Jumlah parameter input acak digunakan dan tipe data nilai balik adalah STRING dan DATETIME.

    @Resolve('->double, bigint, string')

    Tidak ada parameter input yang digunakan, dan tipe data nilai balik adalah DOUBLE, BIGINT, dan STRING.

    @Resolve("array<string>,struct<a1:bigint,b1:string>,string->map<string,bigint>,struct<b1:bigint>")

    Tipe data parameter input adalah ARRAY, STRUCT, dan MAP. Tipe data nilai balik adalah MAP dan STRUCT.

    Tipe Data

    Dalam MaxCompute, edisi tipe data yang berbeda mendukung tipe data yang berbeda. Dalam MaxCompute V2.0 dan versi berikutnya, lebih banyak tipe data dan tipe data kompleks, seperti ARRAY, MAP, dan STRUCT, didukung. Untuk informasi lebih lanjut tentang edisi tipe data MaxCompute, lihat Edisi tipe data.

    Tabel berikut menjelaskan pemetaan antara tipe data yang didukung oleh proyek MaxCompute, tipe data Java, dan tipe data writable Java. Anda harus menulis Java UDTF berdasarkan pemetaan tersebut untuk memastikan konsistensi tipe data. Tabel berikut menjelaskan pemetaan tipe data.

    Tipe MaxCompute

    Tipe Java

    Tipe Writable Java

    TINYINT

    java.lang.Byte

    ByteWritable

    SMALLINT

    java.lang.Short

    ShortWritable

    INT

    java.lang.Integer

    IntWritable

    BIGINT

    java.lang.Long

    LongWritable

    FLOAT

    java.lang.Float

    FloatWritable

    DOUBLE

    java.lang.Double

    DoubleWritable

    DECIMAL

    java.math.BigDecimal

    BigDecimalWritable

    BOOLEAN

    java.lang.Boolean

    BooleanWritable

    STRING

    java.lang.String

    Text

    VARCHAR

    com.aliyun.odps.data.Varchar

    VarcharWritable

    BINARY

    com.aliyun.odps.data.Binary

    BytesWritable

    DATE

    java.sql.Date

    DateWritable

    DATETIME

    java.util.Date

    DatetimeWritable

    TIMESTAMP

    java.sql.Timestamp

    TimestampWritable

    INTERVAL_YEAR_MONTH

    N/A

    IntervalYearMonthWritable

    INTERVAL_DAY_TIME

    N/A

    IntervalDayTimeWritable

    ARRAY

    java.util.List

    N/A

    MAP

    java.util.Map

    N/A

    STRUCT

    com.aliyun.odps.data.Struct

    N/A

    Catatan

    Anda hanya dapat menggunakan tipe data writable Java untuk parameter input atau nilai balik UDTF jika proyek MaxCompute Anda menggunakan edisi tipe data MaxCompute V2.0.

    Petunjuk

    Setelah Anda mengembangkan Java UDTF dengan mengikuti petunjuk dalam Proses pengembangan, Anda dapat menggunakan SQL MaxCompute untuk memanggil Java UDTF. Anda dapat menggunakan salah satu dari metode berikut untuk memanggil Java UDTF:

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

    • Gunakan UDF lintas proyek: Gunakan UDF dari Proyek B di Proyek A. Pernyataan berikut menunjukkan contohnya: 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 berdasarkan paket.

    Untuk informasi lebih lanjut tentang cara menggunakan MaxCompute Studio untuk mengembangkan dan memanggil Java UDTF, lihat Contoh.

    Contoh

    Contoh ini menjelaskan cara menggunakan MaxCompute Studio untuk mengembangkan dan memanggil Java UDTF.

    1. Buat persiapan.

      Sebelum Anda menggunakan MaxCompute Studio untuk mengembangkan dan men-debug UDF, Anda harus menginstal MaxCompute Studio dan menghubungkan MaxCompute Studio ke proyek MaxCompute. Untuk informasi lebih lanjut tentang cara menginstal MaxCompute Studio dan menghubungkan MaxCompute Studio ke proyek MaxCompute, lihat topik-topik berikut:

      1. Instal MaxCompute Studio

      2. Hubungkan ke proyek MaxCompute

      3. Buat modul Java MaxCompute

    2. Tulis kode UDTF.

      1. Di panel navigasi kiri tab Project, pilih src > main > java, klik kanan java, lalu pilih New > MaxCompute Java.新建Java Class

      2. Di kotak dialog Create new MaxCompute java class, klik UDTF, masukkan nama di bidang Name, lalu tekan Enter. Dalam contoh ini, kelas Java diberi nama MyUDTF.选择类型并填写名称

        Name: nama kelas Java MaxCompute. Jika Anda belum membuat paket, tentukan parameter ini dalam format packagename.classname. Sistem akan secara otomatis menghasilkan paket.

      3. Tulis kode di editor kode. 编写UDTF代码Contoh berikut menunjukkan kode UDTF.

        package org.alidata.odps.udtf.examples;
import com.aliyun.odps.udf.UDTF;
import com.aliyun.odps.udf.UDTFCollector;
import com.aliyun.odps.udf.annotation.Resolve;
import com.aliyun.odps.udf.UDFException;
// TODO definisikan tipe input dan output, misalnya, "string,string->string,bigint".
   @Resolve("string,bigint->string,bigint")
   public class MyUDTF extends UDTF {
     @Override
     public void process(Object[] args) throws UDFException {
       String a = (String) args[0];
       Long b = (Long) args[1];
       for (String t: a.split("\\s+")) {
         forward(t, b);
       }
     }
   }

    3. Debug UDTF di mesin lokal Anda untuk memastikan bahwa kode dapat berjalan dengan sukses.

      Untuk informasi lebih lanjut tentang operasi debug, lihat Lakukan run lokal untuk men-debug UDF.

      本地调试UDTF

      Catatan

      Pengaturan parameter pada gambar sebelumnya hanya untuk referensi.

    4. Kemas UDTF yang dibuat ke dalam file JAR, unggah file tersebut ke proyek MaxCompute Anda, lalu daftarkan UDTF. Dalam contoh ini, nama fungsi adalah user_udtf.

      Untuk informasi lebih lanjut tentang cara mengemas UDTF, lihat Prosedur.

      注册函数

    5. Di panel navigasi kiri MaxCompute Studio, klik Project Explorer. Klik kanan proyek MaxCompute Anda, pilih Open in Console dari daftar drop-down untuk memulai klien MaxCompute, lalu jalankan pernyataan SQL untuk memanggil UDTF baru.

      Contoh berikut menunjukkan struktur data tabel my_table yang ingin Anda kueri.

      +------------+------------+
| col0       | col1       |
+------------+------------+
| A B        | 1          |
| C D        | 2          |
+------------+------------+

      Jalankan pernyataan SQL berikut untuk memanggil UDTF:

      select user_udtf(col0, col1) as (c0, c1) from my_table;

      Hasil berikut dikembalikan:

      +----+------------+
| c0 | c1         |
+----+------------+
| A  | 1          |
| B  | 1          |
| C  | 2          |
| D  | 2          |
+----+------------+

    Referensi

    Untuk informasi lebih lanjut tentang cara menggunakan Java UDTF, lihat Contoh-contoh Java UDTF.