使用參數配合管線

管線參數允許你在不同環境或資料集中重用相同的管線原始碼。例如，你可以對 dev 和 prod 目錄執行相同的轉換，或在每次執行時從不同的來源路徑擷取資料。你可以在管線上定義參數（或在更新啟動時覆寫它們），並從你的 SQL 原始碼中引用它們。

管線參數僅提供給 SQL 原始碼。若要在管線中將 Python 原始碼參數化，請使用Configuration欄位，如使用 Configuration 欄位參照參數所述。 Configuration 也用來設定 Spark 的組態值，供管線在執行階段讀取。關於 Spark 設定的詳細資訊，請參閱管線屬性參考。

什麼是管線參數？

管線參數是鍵/值組，可讓你：

在管線設定中宣告為預設值。
可在從管線 UI、啟動更新 API或「以不同設定執行」對話方塊啟動更新時覆寫。
在作業中覆寫管線任務，並可選擇將作業層級參數向下傳遞。
參考來自 SQL 原始碼，使用指定的參數語法。

參數值永遠是字串。鍵可以包含字母數字、底線（）、_連字號（-）和句點（.）。

管線參數與配置欄位有不同的功能：

使用參數來...	使用設定來...
這些值會在更新間改變（目標目錄、來源路徑、日期範圍）。	控制管線行為的 Spark 設定（`pipelines.enzyme.enabled`、`pipelines.clusterLabelsV2Enabled`）。
你希望從作業或任務向下傳遞的值。	靜態、結構性管線特性。
就是你在 SQL 中用命名參數語法參考的值。	你用 SQL 中的 `${key}` 語法或 `spark.conf.get("key")` 在 Python 中引用的值。

定義管線參數

你可以在管線設定中定義預設參數值。當更新在未覆寫設定的情況下執行時，管線會使用這些預設值。

使用管線使用者介面

在你的工作區中，點選在側邊欄選工作與管道，並選擇你的管道。
點選 [設定]。
在 管線設定 側邊欄，找到參數區塊，點選編輯。
新增鍵與值條目，然後點擊儲存。

使用 JSON 或 REST API

在管線設定中或使用 REST API 時，將 parameters 對應新增至管線的 JSON 定義中：

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

完整管線 JSON 參考，請參見管線配置。

使用 YAML 或宣告式自動化套件

在管線的 YAML 定義映射中定義參數 parameters ，無論是在管線設定中，或是在宣告式自動化套件（什麼是宣告式自動化套件？）中：

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

SQL 原始碼中的參考參數

在鍵前面加上冒號來引用參數。 Azure Databricks 會將值綁定為更新時的字串：

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

若要在識別碼位置使用參數，例如目錄、結構或資料表名稱，請將其包裝為 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;

如果你的原始碼引用的參數在更新時沒有值，更新就會失敗並出現錯誤。管線會忽略程式碼未參考的額外參數。

在更新時覆寫參數

你可以在一次更新中覆寫參數值，而不必改變已儲存的預設值。

在管線介面中，點選 「以不同設定執行 」並編輯參數區塊。
從工作中的管線任務中，設定參數會覆蓋該任務的參數欄位。請參閱參數。
從 API 中，在parameters請求中傳遞一個映射。

Azure Databricks 會在更新歷史中記錄特定更新的參數，並顯示在管線執行清單的 Run parameters欄位中。

參數優先順序

當你在多個地方定義相同的鍵時，優先順序最高的值會勝出。從最高到最低：

工作執行參數：為單一工作執行（覆寫）所提供的值。
工作參數：預設值定義在父工作上。
管線任務參數：設定在管線任務上的值。
管線參數：在管線設定中定義的預設值。

這與其他工作參數任務類型所使用的優先順序相符。

Lakeflow 作業中的管線參數

當你在工作中將管線排程為管線任務時，該任務可以提供覆蓋管線預設值的參數。參數值可使用動態值參照來插入作業執行階段的值，例如 {{job.trigger.time.iso_date}} 或 {{job.parameters.region}}。若要參考上游任務所設定的值，請使用 {{tasks.<task_name>.values.<value_name>}}。請參閱使用任務值在任務之間傳遞資訊。

Lakeflow Jobs 也會自動將所有作業參數傳遞至管線任務，就像也會將這些參數傳遞至筆記本與 SQL 任務一樣。管線原始碼可以使用命名參數語法引用任何下推值。在管線設定中宣告參數是可選的，且僅設定無覆寫的執行預設值。

注意事項與已知限制

管線一次執行一個更新：管線一次只能執行一次更新。為避免在多個更新原本可能重疊時導致作業失敗，Azure Databricks 在兩種情況下會將並行數上限設為 1：
- 包含管線任務且設定為超過一個 max_concurrent_runs 的工作。
- 包裝在 for-each task 中的管線任務，無論迭代次數為何。
當這個上限生效時，職缺介面會顯示通知。設計你打算用多種參數組合運行的參數化管線時，請圍繞這個上限來規劃。

日期篩選器可觸發完整刷新：一個常見的參數化應用是依日期篩選資料。請留意述詞：在日期範圍的兩端都進行篩選，會使實體化檢視的增量處理失效，並在每次更新時觸發完全重新整理。

-- 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;

命名參數僅限 SQL：命名參數語法只能用於 SQL 原始碼。要參數化 Python 原始碼，請使用 Configuration欄位搭配 spark.conf.get()。請參見使用配置欄位的參考參數。

使用配置欄位的參考參數

管線上的配置欄位接受任意的鍵值對，這些組合會被揭露為 Spark 設定值。這是舊有的參數化機制，並持續與管線參數並行運作。將它用於 Python 原始碼，以及用於你想以 spark.conf.get() 而非命名參數語法讀取的鍵。

以下範例使用 mypipeline.start_date 設定值，將開發管線限制為僅使用輸入資料的子集：

SQL

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

Python

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)

你可以在管線設定的 Configuration 區段中，或在管線 JSON 的 configuration 欄位中設定設定值。避免使用與保留的管線或 Apache Spark 設定值衝突的金鑰。

其他資源

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-10-12