Gunakan kembali logika SQL dengan template script di DataWorks - DataWorks - Alibaba Cloud - DataWorks

Templat skrip adalah templat yang dapat digunakan kembali untuk proses kode SQL yang mencakup parameter input dan output. Anda dapat menggunakan templat skrip untuk memproses data dari tabel sumber dengan melakukan operasi seperti filtering, joining, dan agregasi guna menghasilkan tabel output. Topik ini memperkenalkan templat skrip serta menjelaskan cara membuat dan menggunakannya.

Ikhtisar templat skrip

Pendahuluan

Dalam banyak skenario pemrosesan data, Anda mungkin menulis kode SQL serupa di mana hanya nama tabel input dan output yang berbeda, sedangkan skema mereka tetap identik atau kompatibel. Untuk menghindari pekerjaan berulang, Anda dapat mengenkapsulasi logika tersebut ke dalam templat skrip. Dengan mendefinisikan nama tabel variabel sebagai parameter input dan output, Anda dapat menggunakan kembali kode SQL yang sama untuk berbagai sumber data.

Setelah membuat node SQL Snippet, Anda dapat menerapkan dan menjadwalkannya seperti node SQL lainnya. Pendekatan ini secara signifikan meningkatkan efisiensi pengembangan dengan mendorong penggunaan ulang kode.

Izin

Anda harus memiliki role Development di ruang kerja DataWorks untuk membuat dan menggunakan templat skrip. Untuk informasi lebih lanjut tentang cara menetapkan role, lihat Tambahkan anggota ruang kerja dan tetapkan role kepada anggota tersebut.

Batasan

Fitur node SQL Snippet hanya tersedia di DataWorks Edisi Standar dan versi setelahnya. Untuk informasi lebih lanjut, lihat Edisi dan fitur DataWorks.
Templat skrip yang dibuat oleh anggota ruang kerja saat ini ditampilkan di bawah tab Component.
Templat skrip yang dibuat oleh anggota tenant ditampilkan di bawah tab Public.

Jenis templat skrip

Templat skrip dikategorikan sebagai tingkat ruang kerja atau publik. Developer yang membuat templat skrip dapat menentukan jenisnya.

Templat skrip tingkat ruang kerja: Setelah templat skrip tingkat ruang kerja dipublikasikan, templat tersebut hanya dapat digunakan oleh pengguna dalam ruang kerja DataWorks yang sama. Untuk menggunakan jenis templat ini, Anda harus menjadi anggota ruang kerja tersebut. Untuk informasi lebih lanjut, lihat Tambahkan anggota ruang kerja dan tetapkan role kepada anggota tersebut.
Templat skrip publik: Developer dapat menggunakan fitur Publish Snippet untuk menyediakan templat skrip tujuan umum kepada seluruh tenant. Setelah dipublikasikan, templat skrip tersebut tersedia untuk semua pengguna dalam tenant tersebut.

Alur kerja

Component yang dibuat di DataWorks harus digunakan bersama SQL Snippet. Alur kerjanya sebagai berikut:

Definisikan templat skrip

Di panel Component Management DataStudio, developer mendefinisikan proses kode SQL beserta parameter input dan output-nya. Proses SQL abstrak ini mengambil tabel input tertentu sebagai parameter input, memprosesnya, lalu menghasilkan tabel output. Di dalam kode, parameter input dan output menggunakan format @@{ParameterName}.
- Jenis parameter input berikut didukung:
  - Table: Gunakan tipe ini untuk input berbasis tabel.
  - String: Gunakan tipe ini untuk meneruskan nilai variabel, seperti kondisi filter, ke dalam SQL Anda.
- Dalam praktiknya, parameter output sebaiknya dikonfigurasi sebagai tipe Table.
Referensikan templat skrip

Di halaman DataStudio, pengguna membuat node SQL Snippet, mereferensikan templat skrip yang diperlukan, lalu mengonfigurasi parameter input dan output untuk menggunakan kembali kode tersebut.

Definisikan templat skrip

Buka halaman Snippets

Buka halaman DataStudio.

Masuk ke Konsol DataWorks. Di wilayah target, klik Data Development and O&M > Data Development di panel navigasi sebelah kiri. Pilih ruang kerja dari daftar drop-down lalu klik Go to Data Development.
Di panel navigasi sebelah kiri, klik Component Management untuk membuka halaman manajemen snippet.

Catatan
Jika Component Management tidak ditampilkan di panel navigasi sebelah kiri, klik ikon di pojok kiri bawah lalu tambahkan di bagian Module Management.

Buat dan konfigurasikan templat skrip

Bagian ini menjelaskan cara developer membuat templat skrip di Component Management untuk mengabstraksikan proses SQL tertentu menjadi templat yang dapat digunakan kembali. Templat skrip biasanya terdiri atas proses kode SQL, parameter input, dan parameter output. Proses kode SQL mendefinisikan kode implementasi untuk fungsionalitas templat. Di dalam proses ini, Anda menggunakan format @@{VariableName} untuk mendefinisikan placeholder bagi tabel input, string, dan tabel output. Placeholder ini berfungsi sebagai parameter input dan output templat, sehingga memungkinkan penggunaan ulang kode SQL.

Catatan

Templat skrip dapat memiliki beberapa parameter input dan output.

Sebagai contoh, kode isi proses dapat berupa INSERT OVERWRITE TABLE @@{my_output} SELECT ... FROM @@{my_input} WHERE col1 = @@{my_input_parameter1} AND col2 = @@{my_input_parameter2}, di mana @@{my_output} adalah parameter tabel output, @@{my_input} adalah parameter tabel input, dan @@{my_input_parameter1} serta @@{my_input_parameter2} adalah parameter string input.

Langkah 1: Buat templat skrip

Di halaman Snippets, Anda dapat membuat templat skrip dengan salah satu cara berikut:

Metode 1: Di panel Snippets sebelah kiri, klik kanan node Snippets lalu pilih New > Snippet.
Metode 2: Di bilah alat di bagian atas panel Snippets, klik ikon New lalu pilih New > Snippet.

Catatan

Templat skrip yang dibuat oleh anggota ruang kerja saat ini ditampilkan di bawah tab Component.
Templat skrip yang dibuat oleh anggota tenant ditampilkan di bawah tab Public.

Langkah 2: Konfigurasikan templat skrip

Konfigurasikan proses kode SQL.

Proses kode SQL berisi kode implementasi templat skrip. Dengan menulis kode SQL abstrak dan menggunakan format @@{ParameterName} untuk memasukkan parameter input dan output, Anda dapat memproses tabel input tertentu dan menghasilkan tabel output yang bernilai. Saat menggunakan templat nanti, Anda mengonfigurasi parameter input dan output yang berbeda untuk menghasilkan kode SQL valid dari templat ini.

Konfigurasikan parameter input.

Definisikan parameter input untuk proses kode SQL. Tipe yang didukung adalah Table dan String.

Table: Gunakan tipe ini untuk input berbasis tabel.

Tabel berikut menjelaskan konfigurasi utama untuk tipe ini.

Parameter	Deskripsi	Contoh
Parameter definition	Mendefinisikan skema yang diharapkan untuk tabel input, termasuk nama kolom, tipe data, dan komentar. Untuk mencegah error waktu proses, tabel yang Anda berikan harus memiliki jumlah kolom yang sama dan tipe data yang kompatibel seperti yang didefinisikan di sini. Catatan Definisi ini berfungsi sebagai panduan dan tidak memicu pemeriksaan langsung atau wajib.	Format yang direkomendasikan adalah: `Column1Name Column1Type 'Column1Comment' Column2Name Column2Type 'Column2Comment' ... ColumnNName ColumnNType 'ColumnNComment'` Contoh: `area_id string ‘Area ID’ city_id string ‘City ID’ order_amt double ‘Order amount’`

String: Gunakan tipe ini untuk meneruskan nilai variabel, seperti kondisi filter, ke dalam SQL Anda.

Tabel berikut menjelaskan konfigurasi utama untuk tipe ini.

Item	Deskripsi
Default value	Nilai ini digunakan secara otomatis kecuali ditimpa.
Example scenarios	Scenario 1: Jika tabel output perlu menampilkan penjualan N kota teratas di setiap wilayah, Anda dapat menetapkan N sebagai parameter input. Nilai N dapat dikontrol dengan menggunakan parameter bertipe string. Scenario 2: Jika tabel output perlu menampilkan total penjualan provinsi tertentu, Anda dapat menetapkan parameter string provinsi sebagai parameter input. Dengan menentukan provinsi yang berbeda, Anda dapat mengambil data penjualan yang sesuai.

Konfigurasikan parameter output.

Definisikan parameter output untuk proses kode SQL, yang merepresentasikan tabel output akhir dari templat skrip. Untuk membantu pengguna lain, Anda dapat menentukan skema tabel output di konfigurasi parameter sebagai referensi mereka.

Tabel berikut menjelaskan konfigurasi utama untuk parameter output:

Parameter	Deskripsi	Contoh
Parameter definition	Mendefinisikan skema yang diharapkan untuk tabel output, termasuk nama kolom, tipe data, dan komentar. Untuk mencegah error waktu proses, tabel yang Anda berikan harus memiliki jumlah kolom yang sama dan tipe data yang kompatibel seperti yang didefinisikan di sini. Catatan Definisi ini berfungsi sebagai panduan dan tidak memicu pemeriksaan langsung atau wajib.	Format yang direkomendasikan adalah: `Column1Name Column1Type 'Column1Comment' Column2Name Column2Type 'Column2Comment' ... ColumnNName ColumnNType 'ColumnNComment'` Selain itu, Anda dapat menambahkan kolom ringkasan ke definisi parameter output berdasarkan hasil pemrosesan yang diinginkan, seperti rank atau total pendapatan. Contoh: `area_id string ‘Area ID’ city_id string ‘City ID’ order_amt double ‘Order amount’ rank bigint ‘Rank’`

Langkah 3: Simpan dan commit templat skrip

Klik ikon untuk menyimpan templat skrip, lalu klik ikon untuk melakukan commit. Setelah templat skrip dibuat, Anda dapat mereferensikannya di node SQL Snippet untuk dengan cepat menghasilkan tabel yang diperlukan untuk bisnis Anda. Untuk informasi lebih lanjut, lihat Referensikan templat skrip.

Referensikan templat skrip

Prasyarat

Templat skrip telah dibuat dan siap digunakan. Untuk informasi lebih lanjut, lihat Definisikan templat skrip.
Buat node SQL Snippet. Untuk informasi lebih lanjut, lihat Buat dan kelola node MaxCompute.

Referensikan templat skrip

Di tab konfigurasi node SQL Snippet, referensikan templat skrip. Dalam contoh ini, pilih templat skrip get_top_n (V1) dan konfigurasikan nilai parameter di panel Parameter Configuration di sebelah kanan:

Parameter input myinputtable: tipe adalah table, nilai adalah company_sales_record
Parameter input topn: tipe adalah string, nilai adalah 10
Parameter output myoutput: tipe adalah table, nilai adalah company_sales_top_n

Pilih templat skrip yang ingin Anda gunakan.

Jika tidak ada templat skrip yang tersedia, buatlah terlebih dahulu. Untuk informasi lebih lanjut, lihat Definisikan templat skrip.
- Jika tersedia versi baru dari templat skrip yang dipilih, Anda dapat mengklik Update Code untuk menggunakan versi terbaru.
- Klik Edit Snippet untuk melihat detail templat skrip.
Konfigurasikan nilai parameter untuk templat skrip sesuai kasus penggunaan Anda.

Langkah selanjutnya

Setelah selesai mengembangkan node, Anda dapat melakukan operasi berikut:

Konfigurasikan properti penjadwalan: Jika node memerlukan eksekusi berkala, konfigurasikan properti penjadwalannya, seperti pengaturan rerun dan dependensi. Untuk informasi lebih lanjut, lihat Ikhtisar konfigurasi penjadwalan task.
Lakukan debugging node: Jalankan node untuk menguji kodenya dan memverifikasi logika. Untuk informasi lebih lanjut, lihat Proses debugging node.
Terapkan task: Setelah selesai pengembangan, terapkan task tersebut. Setelah diterapkan, node akan berjalan secara berkala sesuai konfigurasi penjadwalannya. Untuk informasi lebih lanjut, lihat Terapkan task.

Kelola templat skrip

Publikasikan dan lihat penggunaan

Anda dapat mempublikasikan templat skrip atau melihat catatan penggunaannya sesuai kebutuhan.

Publish Snippet: Fitur ini meningkatkan templat skrip tingkat ruang kerja menjadi templat skrip publik, sehingga tersedia untuk semua pengguna dalam tenant. Secara default, templat skrip baru hanya tersedia dalam ruang kerjanya sendiri.
Snippet Nodes: Anda dapat melihat node mana saja yang menggunakan templat skrip saat ini. Hal ini membantu Anda menilai dampak sebelum melakukan perubahan pada templat.

Tingkatkan templat skrip

Proses peningkatan untuk developer

Developer dapat mengedit kode templat skrip dan konfigurasi parameternya sesuai kebutuhan. Setelah menyimpan dan melakukan commit perubahan, templat ditingkatkan ke versi baru. Anda dapat melihat detail setiap versi di riwayat versi.

Tulis kode SQL berparameter berikut di editor templat skrip. Gunakan @@{} untuk mereferensikan parameter input dan output, serta gunakan ${} untuk mereferensikan parameter penjadwalan:

insert overwrite table @@{my_output_table}
partition (ds='${bizdate}')
select
    *
from
    @@{my_input_table}
where   category in ('@@{my_input_parameter1}', '@@{my_input_parameter2}')
  AND   substr(pt, 1, 8) in ('${bizdate}')
;

Dampak peningkatan versi terhadap pengguna

Setelah templat skrip ditingkatkan, jika node SQL Snippet Anda mereferensikannya, Anda dapat memilih apakah akan menggunakan versi terbaru atau tidak. Jika tidak, Anda dapat terus menggunakan versi lama. Jika memilih untuk meningkatkan, Anda harus memverifikasi bahwa konfigurasi parameter baru masih valid untuk node SQL Snippet Anda dan melakukan penyesuaian yang diperlukan berdasarkan deskripsi versi baru tersebut. Setelah mengedit, lakukan commit dan terapkan node tersebut. Proses penerapan sama seperti node SQL biasa. Untuk meningkatkan, lakukan langkah-langkah berikut:

Di pemilih templat skrip di bagian atas editor kode, pilih versi templat (misalnya Snippet (V1)), lalu tentukan apakah Anda perlu mengklik Update Code Version untuk menggunakan versi baru.
Di panel Parameter Configuration di sebelah kanan, konfigurasikan Input Parameters (misalnya nama parameter table1, tipe string) dan Output Parameters (misalnya nama parameter table2, tipe string) dengan nilai yang sesuai.

Contoh peningkatan

Developer C membuat versi V1.0 templat skrip, yang mulai digunakan oleh Pengguna A. Kemudian, Developer C meningkatkan templat tersebut ke V2.0. Saat menggunakan node, Pengguna A melihat bahwa versi baru V2.0 tersedia. Pengguna A dapat membuka templat, melihat detail berbagai versi, lalu membandingkannya. Jika versi baru memberikan hasil bisnis yang lebih baik, Pengguna A dapat memperbarui node untuk menggunakan versi terbaru templat skrip tersebut.

Referensi

Fitur UI

Feature	Deskripsi
Save	Menyimpan pengaturan saat ini dari templat skrip.
Steal lock editing	Memungkinkan Anda mengambil kendali pengeditan node yang dikunci oleh pengguna lain.
Submission	Menyerahkan templat skrip saat ini ke lingkungan pengembangan.
Publish Snippet	Memublikasikan templat skrip tujuan umum ke seluruh tenant, sehingga terlihat dan dapat digunakan oleh semua pengguna dalam tenant tersebut.
Parse I/O Parameters	Mengurai parameter input dan output dari kode saat ini.
Running	Menjalankan templat skrip di lingkungan pengembangan.
Stop	Menghentikan templat skrip yang sedang berjalan.
Format	Memformat kode templat skrip berdasarkan kata kunci SQL.
Parameter Configuration	Konfigurasikan informasi templat skrip, parameter input, dan parameter output.
Version	Menampilkan riwayat commit templat skrip.
Snippet Nodes	Menampilkan daftar semua node yang menggunakan templat skrip ini.

Praktik terbaik

Prasyarat

Node SQL Snippet telah dibuat. Untuk informasi lebih lanjut, lihat Buat dan kelola node MaxCompute.
Buat tabel input dan tabel output di node ODPS SQL.

Definisikan templat skrip

Pertama, buat templat skrip bernama get_top_n seperti yang dijelaskan di Definisikan templat skrip. Berikut adalah detail konfigurasinya.

Konfigurasi parameter

Kategori	Nama parameter	Tipe	Deskripsi	Definisi parameter
Parameter input	myinputtable	Table	Tabel data detail penjualan yang ditentukan.	`area_id string city_id string order_amt double rank bigint`
Parameter input	topn	String	Jumlah peringkat penjualan teratas yang akan diambil.	N/A
Parameter output	myoutput	Table	Tabel output yang menyimpan peringkat N kota teratas untuk setiap wilayah.	`area_id string city_id string order_amt double rank bigint`

Definisi proses kode SQL

INSERT OVERWRITE TABLE  @@{myoutput}  PARTITION (pt='${bizdate}')
 SELECT r3.area_id,
 r3.city_id,
 r3.order_amt,
 r3.rank
from (
SELECT
   area_id,
   city_id,
   rank,
   order_amt_1505468133993_sum as order_amt ,
   order_number_1505468133991_sum,
   profit_amt_1505468134000_sum
FROM
   (SELECT
   area_id,
   city_id,
   ROW_NUMBER() OVER (PARTITION BY r1.area_id ORDER BY r1.order_amt_1505468133993_sum DESC) AS rank,
   order_amt_1505468133993_sum,
   order_number_1505468133991_sum,
   profit_amt_1505468134000_sum
FROM
   (SELECT
   area AS area_id,
   city AS city_id,
   SUM(order_amt) AS order_amt_1505468133993_sum,
   SUM(order_number) AS order_number_1505468133991_sum,
   SUM(profit_amt) AS profit_amt_1505468134000_sum
FROM
  @@{myinputtable}
WHERE
   SUBSTR(pt, 1, 8) IN ( '${bizdate}' )
GROUP BY
   area,
   city )
   r1 ) r2
WHERE
   r2.rank >= 1 AND r2.rank <= @@{topn}
ORDER BY
   area_id,
   rank limit 10000) r3;

Gunakan templat skrip

Buat node SQL Snippet bernama xc_ref_snippet_get_top_n, referensikan templat skrip get_top_n yang dibuat di Langkah 1, lalu konfigurasikan parameternya. Untuk informasi lebih lanjut, lihat Referensikan templat skrip.

Di editor komponen kode, pilih templat skrip get_top_n (V1). Logika SQL di editor kode sebelah kiri menggunakan INSERT OVERWRITE TABLE @@{myoutput} untuk menulis hasil ke tabel output, menggunakan fungsi jendela ROW_NUMBER() OVER (PARTITION BY ...) untuk memberi peringkat kota berdasarkan penjualan dalam setiap wilayah, serta menghitung total penjualan menggunakan SUM(order_amt). Konfigurasikan parameter input dan output di panel Parameter Configuration di sebelah kanan. Parameter dikonfigurasi sebagai berikut:

Parameter input myinputtable: Tentukan tabel input bernama company_sales_record sebagai sumber data. Skema tabel input adalah sebagai berikut:

company_sales_record

CREATE TABLE IF NOT EXISTS company_sales_record
(
    order_id         STRING COMMENT 'Order ID (primary key)',
    report_date      STRING COMMENT 'Order date',
    customer_name    STRING COMMENT 'Customer name',
    order_level      STRING COMMENT 'Order level',
    order_number     DOUBLE COMMENT 'Order quantity',
    order_amt        DOUBLE COMMENT 'Order amount',
    back_point       DOUBLE COMMENT 'Discount points',
    shipping_type    STRING COMMENT 'Shipping method',
    profit_amt       DOUBLE COMMENT 'Profit amount',
    price            DOUBLE COMMENT 'Unit price',
    shipping_cost    DOUBLE COMMENT 'Shipping cost',
    area             STRING COMMENT 'Area',
    province         STRING COMMENT 'Province',
    city             STRING COMMENT 'City',
    product_type     STRING COMMENT 'Product type',
    product_sub_type STRING COMMENT 'Product sub-type',
    product_name     STRING COMMENT 'Product name',
    product_box      STRING COMMENT 'Product package',
    shipping_date    STRING COMMENT 'Shipping date'
) 
COMMENT 'Detailed sales information'
PARTITIONED BY
(
    pt               STRING
)
LIFECYCLE 365;

Parameter input topn: Tentukan jumlah kota berperingkat teratas yang akan diambil untuk setiap wilayah, diurutkan berdasarkan jumlah penjualan. Dalam contoh ini, nilainya adalah 10.

Parameter output myoutput: Tentukan nama tabel untuk output yang diproses, yaitu company_sales_top_n. Skema tabel output adalah sebagai berikut:

company_sales_top_n

CREATE TABLE IF NOT EXISTS company_sales_top_n
( 
area STRING COMMENT 'Area', 
city STRING COMMENT 'City', 
sales_amount DOUBLE COMMENT 'Sales amount', 
rank BIGINT COMMENT 'Rank'
)
COMMENT 'Company sales ranking'
PARTITIONED BY (pt STRING COMMENT '')
LIFECYCLE 365;