Menggunakan parameter dengan alur

Parameter alur memungkinkan Anda menggunakan kembali kode sumber alur yang sama di seluruh lingkungan atau himpunan data. Misalnya, Anda dapat menjalankan transformasi yang sama pada katalog dev dan prod, atau memasukkan data dari jalur sumber yang berbeda setiap kali dijalankan. Anda menentukan parameter pada alur (atau menimpanya saat memulai pembaruan) dan mereferensikannya dari kode sumber SQL Anda.

Penting

Fitur ini ada di Beta. Admin ruang kerja dapat mengontrol akses ke fitur ini dari halaman Pratinjau . Lihat Kelola Pratinjau Azure Databricks.

Parameter alur hanya tersedia untuk kode sumber SQL. Untuk membuat kode sumber Python menjadi berparameter dalam pipeline, gunakan kolom Konfigurasi seperti yang dijelaskan dalam Mereferensikan parameter menggunakan kolom konfigurasi. Konfigurasi juga digunakan untuk menetapkan nilai konfigurasi Spark yang dibaca oleh pipeline saat runtime. Untuk detail mengenai pengaturan konfigurasi Spark, lihat Referensi properti pipeline.

Apa itu parameter alur?

Parameter alur adalah pasangan kunci-nilai yang dapat Anda:

Tetapkan sebagai standar di pengaturan pipeline.
Ambil alih saat memulai pembaruan dari UI alur, MULAI perbarui API, atau dialog Jalankan dengan pengaturan yang berbeda .
Timpa tugas pipeline dalam sebuah pekerjaan, dengan opsi meneruskan parameter tingkat pekerjaan.
Referensi dari kode sumber SQL menggunakan sintaks parameter bernama .

Nilai parameter selalu string. Kunci dapat berisi karakter alfanumerik, garis bawah (_), tanda hubung (-), dan titik (.).

Parameter alur dan bidang Konfigurasi melayani tujuan yang berbeda:

Gunakan Parameter untuk...	Gunakan Konfigurasi untuk...
Nilai yang berubah di antara pembaruan (katalog target, jalur sumber, rentang tanggal).	Konfigurasi Spark yang mengontrol perilaku alur (`pipelines.enzyme.enabled`, `pipelines.clusterLabelsV2Enabled`).
Nilai yang ingin Anda dorong dari pekerjaan atau tugas.	Properti alur statis dan struktural.
Nilai yang Anda referensikan di SQL dengan sintaks parameter bernama.	Nilai yang Anda referensikan dengan sintaks `${key}` dalam SQL atau `spark.conf.get("key")` di Python.

Menentukan parameter alur

Anda dapat menentukan nilai parameter default dalam pengaturan alur. Saat pembaruan berjalan tanpa penimpaan, alur menggunakan default ini.

Gunakan antarmuka pengguna pipeline

Di ruang kerja Anda, klik Pekerjaan dan Alur di bar samping dan pilih alur Anda.
Klik Pengaturan.
Di bilah samping Pengaturan alur , temukan bagian Parameter dan klik Edit.
Tambahkan entri Kunci dan Nilai , lalu klik Simpan.

Menggunakan JSON atau REST API

parameters Tambahkan peta ke definisi JSON alur, baik dalam pengaturan alur atau saat menggunakan REST API:

{
  "name": "Sales pipeline",
  "parameters": {
    "source_catalog": "dev_catalog",
    "source_schema": "sales",
    "start_date": "2026-01-01"
  }
}

Untuk referensi JSON alur lengkap, lihat Konfigurasi alur.

Menggunakan YAML atau Bundel Otomatisasi Deklaratif

Tentukan parameter dalam pemetaan parameters pada definisi YAML pipeline, baik di pengaturan pipeline maupun dalam Bundel Otomatisasi Deklaratif (Apa itu Bundel Otomatisasi Deklaratif?):

resources:
  pipelines:
    my_pipeline:
      name: Sales pipeline
      parameters:
        source_catalog: dev_catalog
        source_schema: sales
        start_date: '2026-01-01'

Parameter referensi dalam kode sumber SQL

Rujuk parameter dengan menambahkan titik dua di depan kunci. Azure Databricks mengikat nilai sebagai string pada waktu pembaruan:

CREATE OR REFRESH MATERIALIZED VIEW transaction_summary AS
SELECT account_id,
  COUNT(txn_id) AS txn_count,
  SUM(txn_amount) AS account_revenue
FROM :source_catalog.sales.transactions
WHERE txn_date >= :start_date
GROUP BY account_id

Untuk menggunakan parameter pada posisi identifier, seperti katalog, skema, atau nama tabel, bungkus parameter tersebut dengan IDENTIFIER():

USE CATALOG IDENTIFIER(:source_catalog);
USE SCHEMA IDENTIFIER(:source_schema);

CREATE OR REFRESH MATERIALIZED VIEW daily_sales AS
SELECT date(timestamp) AS date,
  SUM(price) AS total_sales
FROM transactions
GROUP BY date;

Jika kode sumber Anda mereferensikan parameter yang tidak memiliki nilai pada waktu pembaruan, pembaruan gagal dengan kesalahan. Pipeline mengabaikan parameter tambahan yang tidak dirujuk oleh kode.

Ganti parameter saat pembaruan

Anda dapat mengambil alih nilai parameter untuk satu pembaruan tanpa mengubah default yang disimpan.

Di UI pipeline, klik Jalankan dengan pengaturan berbeda dan edit bagian Parameter.
Dari tugas pipeline dalam suatu job, atur penggantian parameter di kolom Parameters milik tugas. Lihat Parameter.
Dari API, sertakan parameters map dalam permintaan Mulai pembaruan.

Azure Databricks merekam parameter untuk pembaruan tertentu di riwayat pembaruan dan menampilkannya di kolom Run parameters pada daftar eksekusi alur.

Urutan prioritas parameter

Ketika Anda menentukan kunci yang sama di lebih dari satu tempat, nilai dengan prioritas tertinggi menang. Dari tertinggi hingga terendah:

Parameter eksekusi pekerjaan: nilai yang disediakan untuk satu eksekusi pekerjaan (penimpaan).
Parameter pekerjaan: default yang ditentukan pada pekerjaan induk.
Parameter tugas pipeline: nilai yang ditetapkan pada tugas pipeline.
Parameter alur: default yang ditentukan dalam pengaturan alur.

Ini cocok dengan prioritas yang digunakan oleh jenis tugas parameter pekerjaan lainnya.

Parameter alur dalam Pekerjaan Lakeflow

Saat Anda menjadwalkan pipeline sebagai tugas pipeline dalam sebuah job, tugas tersebut dapat memberikan parameter yang menggantikan parameter default pipeline. Nilai parameter dapat menggunakan referensi nilai dinamis untuk menyuntikkan nilai job-run-time seperti {{job.trigger.time.iso_date}} atau {{job.parameters.region}}. Untuk merujuk ke nilai yang ditetapkan oleh tugas upstream, gunakan {{tasks.<task_name>.values.<value_name>}}. Lihat bagian tentang cara menggunakan nilai tugas untuk meneruskan informasi antar tugas.

Lakeflow Jobs juga secara otomatis meneruskan semua parameter pekerjaan ke tugas pipeline, sama seperti meneruskannya ke tugas notebook dan SQL. Kode sumber alur dapat mereferensikan nilai yang didorong ke bawah dengan sintaks parameter bernama. Mendeklarasikan parameter dalam pengaturan pipeline bersifat opsional dan hanya menetapkan nilai default untuk eksekusi tanpa penimpaan.

Peringatan dan batasan yang diketahui

Alur menjalankan satu pembaruan pada satu waktu: Alur hanya dapat menjalankan satu pembaruan pada satu waktu. Untuk mencegah pekerjaan gagal ketika beberapa pembaruan akan tumpang tindih, Azure Databricks menutup konkurensi ke 1 dalam dua skenario:
- Pekerjaan yang berisi tugas alur dan dikonfigurasi dengan max_concurrent_runs lebih dari satu.
- Tugas pipeline yang dibungkus dalam tugas for-each, terlepas dari jumlah iterasinya.
UI pekerjaan menunjukkan pemberitahuan ketika batas ini berlaku. Perhitungkan batas maksimum tersebut saat merancang pipeline berparameter yang akan Anda jalankan dengan banyak kombinasi parameter.

Filter tanggal dapat memicu refresh penuh: Kasus penggunaan parameterisasi umum adalah memfilter data menurut tanggal. Berhati-hatilah dengan predikat: pemfilteran di kedua sisi rentang tanggal membatalkan pemrosesan inkremental pada tampilan materialisasi dan memicu refresh penuh pada setiap pembaruan.

-- Triggers a full refresh on each update
CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
SELECT * FROM orders
WHERE order_date >= :start_date AND order_date < :end_date;

-- Processes incrementally
CREATE OR REFRESH MATERIALIZED VIEW recent_orders AS
SELECT * FROM orders
WHERE order_date >= :start_date;

Parameter bernama hanya untuk SQL: Dalam versi Beta ini, sintaks parameter bernama hanya dapat digunakan dalam kode sumber SQL. Untuk membuat parameter kode sumber Python, terus gunakan bidang Configuration dengan spark.conf.get(). Lihat Parameter referensi menggunakan bidang konfigurasi.

Mereferensikan parameter menggunakan kolom konfigurasi

Bidang Konfigurasi pada alur menerima pasangan kunci-nilai arbitrer yang diekspos sebagai nilai konfigurasi Spark. Ini adalah mekanisme parameterisasi warisan dan terus bekerja bersama parameter alur. Gunakan ini untuk kode sumber Python dan untuk kunci yang ingin dibaca dengan spark.conf.get() alih-alih sintaks parameter bernama.

Contoh berikut menggunakan mypipeline.start_date nilai konfigurasi untuk membatasi alur pengembangan ke subset data input:

SQL

CREATE OR REFRESH MATERIALIZED VIEW customer_events
AS SELECT * FROM source_table WHERE date > '${mypipeline.start_date}';

Phyton

from pyspark import pipelines as dp
from pyspark.sql.functions import col

@dp.table
def customer_events():
  start_date = spark.conf.get("mypipeline.start_date")
  return spark.read.table("source_table").where(col("date") > start_date)

Anda mengatur nilai Konfigurasi di bagian Konfigurasi pengaturan alur atau di configuration bidang alur JSON. Hindari kunci yang bertentangan dengan alur yang dipesan atau nilai konfigurasi Apache Spark.

Sumber daya tambahan

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-10