共用方式為

使用參數小工具

當你在查詢中加入 命名參數標記 時，Azure Databricks 會在 UI 中顯示一個參數小工具。 元件讓使用者在不直接編輯查詢的情況下設定參數值。 你可以設定每個小工具的類型、標題和預設值。

參數元件在 SQL 編輯器、筆記本、AI/BI 儀表板和 Genie 空間中都被支援，但在這些表面間的行為有所不同。 本頁描述 SQL 編輯器中的參數元件。 關於其他表面，請參見：

在 SQL 編輯器中，任何參數類型（字串、整數、小數、日期、時間戳）都可以使用任何小工具類型。

設定參數元件

  1. 在你的查詢中加入一個命名參數標記。 介面中會出現一個小工具。
  2. 點擊小工具旁的齒輪圖示即可開啟小工具對話框。 建立小工具對話方塊
  3. 請設定以下欄位：
    • 參數名稱：查詢中出現的參數名稱。 如果你在小工具對話框中更改參數名稱，你也必須在查詢中更改。
    • Widget 標籤：描述該 Widget 的字串
    • 元件類型：控制使用者如何輸入該值。 請參見下方的 Widget 類型 。
    • 參數型別：參數資料型別。 參見 參數類型。
  4. 點擊離開小工具對話框以儲存你的更改。

編輯、移除及重新排序小工具

編輯：點擊小工具旁的齒輪圖示可以重新開啟設定面板。

移除：刪除查詢中的參數標記。 該小工具會自動移除。

重新排序：使用小工具左側的拖曳握柄來重新排序。

小工具類型

Azure Databricks 支援以下類型的查詢參數小工具：

小工具類型 說明
Dropdown 使用者必須從預先定義的清單中選擇。
組合盒 使用者可以從預設清單中選擇，或輸入自訂值。
文字輸入 接受任何自由形式的值，且無提供建議。
多重選擇 使用者可以從預設清單中選擇多個值。
動態下拉選單 從儲存的查詢中填充選項，而非靜態清單。
日期與時間戳記範圍 定義使用 .min 和 .max 參數的起始與結束範圍。

文字輸入

直接接受使用者的自由形式值。 當不需要預設選項時，請使用此小工具。

SELECT * FROM samples.tpch.region WHERE r_name = :region_param

呈現預先定義的數值清單。 使用者必須從列表中選擇——不允許自由形式輸入。 在設定面板輸入允許的值，每行輸入一個。

SELECT * FROM samples.tpch.orders WHERE o_orderstatus = :status_param

若要創建一種下拉選單小工具類型：

  1. 點擊小工具旁 :status_param 的齒輪圖示。
  2. 將 小工具類型 設為 下拉選單。
  3. 將 參數類型 設為 字串。
  4. 請在 參數值的選項 文字輸入欄位中輸入數值。 在每個值之間點擊 新增 或按回車鍵。

下拉式方塊

提供預設的建議值清單，同時也允許使用者輸入列表中未包含的自訂值。 當常見選項方便但又想允許自由輸入時，使用組合盒。

SELECT * FROM samples.tpch.part WHERE p_brand = :brand_param

多選

允許使用者從預設清單中選擇多個值。 選取的值會以集合的形式傳遞給查詢。

SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    CAST(dropoff_zip AS STRING)
  )

要新增多選下拉選單的選項：

  1. 點擊小工具旁 list_parameter 的齒輪圖示。
  2. 將 Widget 類型設為多選。
  3. 將 參數類型 設為 字串。
  4. 在文字輸入欄位中填入參數值的選擇。 在每個值之間點擊 新增 或按回車鍵。

動態下拉選單

備註

動態下拉選單小工具僅在 SQL 編輯器中提供，筆記本中則無法使用。

從儲存的查詢中填入選項清單，而非靜態清單。 隨著底層資料的變動，可用選項會自動更新。

使用動態下拉選單：

  1. 建立並儲存一個查詢，讓下拉選單中回傳你想要的值：

    SELECT DISTINCT c_mktsegment FROM samples.tpch.customer ORDER BY c_mktsegment

  2. 在新的或現有的查詢中，新增一個命名的參數標記：

    SELECT c_custkey, c_name, c_acctbal
FROM samples.tpch.customer
WHERE c_mktsegment = :segment_param

  3. 點擊小工具旁 segment_param 的齒輪圖示。

  4. 將 Widget 類型 設為 動態下拉選單。

  5. 點擊 查詢 欄位以開啟 「選擇現有查詢 」對話框。 從步驟 1 選擇已儲存的查詢，然後點選 Select。

  6. 選擇 一個預設參數值。

  7. 按下 [套用變更]。

日期與時間戳記範圍

日期與時間戳參數支援 範圍小工具 類型。 選擇後，Azure Databricks 會建立兩個參數，使用 .min 和 .max 後綴來定義範圍的起始與結束。

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN CAST(:date_range_min AS TIMESTAMP) AND CAST(:date_range_max AS TIMESTAMP)

點擊藍色閃電圖示以選取動態值，如 today、 yesterday、 this weeklast weeklast monthlast year或 。 這些數值會自動更新。

這很重要

動態日期值與排程查詢不相容。

  • Last updated on