運用儀錶板參數

發行項
02/06/2025

本文說明如何在 AI/BI 儀錶板上使用參數。如果您想要改為了解欄位篩選器，請參閱篩選欄位。

AI/BI 儀錶板參數可讓您在執行期間將不同的值輸入到資料集查詢中。這可讓您在 SQL 查詢中彙總資料之前，依日期和產品類別等條件來篩選資料，進而產生更有效率的查詢和精確分析。參數可以搭配篩選小工具使用，讓儀錶板成為互動式儀錶板，或使用視覺效果小工具，讓數據集更容易重複使用。

儀錶板作者或編輯器會將參數新增至數據集，並將其連接到儀錶板畫布上的一或多個小工具。針對在視覺效果小工具中設定的靜態參數，這些值是由作者或編輯器所設定。針對篩選小工具中使用的參數，儀錶板查看器可以在運行時間選取篩選小工具中的值來與數據互動。此互動會重新執行相關聯的查詢，並根據篩選的資料顯示視覺效果。

參數會直接修改查詢，這很強大。資料集欄位過濾器還可以提供儀錶板的互動性，更多功能，以及在大型資料集上比參數更好的效能。請參閱使用篩選。

將參數新增至查詢

您必須至少具有草稿儀表板的 CAN EDIT 權限，才能將參數新增至儀表板資料集。您可以將參數直接新增至 [數據] 索引標籤中的數據集查詢。

Gif 顯示以下步驟的範例。

若要將參數新增至查詢：

將游標放在您想要在查詢中放置參數的位置。
按一下新增參數 以插入新的參數。

此會使用預設名稱 parameter建立新參數。若要變更預設名稱，請在查詢編輯器中取代它。您也可以在查詢編輯器中輸入此語法來新增參數。

編輯查詢參數

若要編輯參數：

按下參數名稱旁邊的。 [參數詳細資料]對話方塊隨即出現，並包括下列組態選項：
- 關鍵字：代表查詢中參數的關鍵字。這只能透過直接更新查詢中的文字來變更。
- 顯示名稱：篩選編輯器中的名稱。根據預設，標題與關鍵字相同。
- 類型：支援的類型包括字串、日期、日期和時間、數值。
  - 預設類型為字串。
  - 數值資料類型可讓你指定小數或整數。預設數值類型為小數。
- 允許多個選項：選取核取方塊 (checkbox)，讓使用者在執行階段選擇多個參數。
  
  注意
  
  此選取專案可能需要對查詢進行額外的變更。請參閱允許多個選取專案。
按一下 UI 的另一部分以關閉對話方塊。

設定預設參數值

若要執行查詢，請在參數名稱下的文字欄位中輸入參數的預設值，以進行選擇。執行查詢以預覽套用參數值的查詢結果。執行查詢也會儲存預設值。當您在畫布上使用篩選小工具設定此參數時，除非在篩選小工具中指定新的預設值，否則會使用預設值。請參閱使用篩選。

允許多個選取專案

允許多個選取範圍的查詢必須包含 ARRAY_CONTAINS 查詢中的函式。

下列範例顯示 SQL 查詢，可讓您選取多個值，以在運行時間插入查詢中。子句會使用函WHEREARRAY_CONTAINS式。該函式會採用參數關鍵詞和數據行名稱作為自變數。參數必須設定為保留多個值，才能將它插入查詢作為陣列。當查詢執行時，會評估每個數據列，而且包含 l_quantity 符合 :parameter 中至少一個值的所有數據列都是結果集。

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

若要設定預設值：

撰寫數據集查詢，以使用 ARRAY_CONTAINS 函式根據值清單篩選數據列。
按一下參數名稱旁的齒輪圖示。選擇 [允許多個選取項目。

注意

此步驟可讓參數以陣列的形式插入查詢中。如果使用 ARRAY_CONTAINS 函式而不啟用多重選擇，就會發生錯誤。
在顯示名稱下的文字欄位中輸入值。您可以輸入一個以上的值。輸入下一個值之前，請先選取目前的值。

在編輯器中設定預設值。會選取多個值，並以空格分隔。

套用日期範圍參數

您可以使用參數來定義範圍，並只傳回該範圍內的結果。當您選擇下列其中一個參數類型時，您會建立兩個參數，這些參數是由 .min 和 .max 後綴所指定：

日期範圍
日期和時間範圍

下列範例顯示建立名為 date_param的日期範圍參數的 SQL 查詢。

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

若要建立日期範圍參數：

按兩下 [ 新增參數]。
按下參數名稱旁邊的。 輸入關鍵詞和顯示名稱。請勿包含 .min 或 .max 後綴。
選擇 [日期範圍 ] 或 [日期和時間範圍 ] 作為 [ 類型]。
將定義範圍的 WHERE 子句插入至您的查詢中。若要定義範圍，請使用 BETWEEN 子句來設定 .min 和 .max 的值。例如：
```
 WHERE date_col BETWEEN :date_param.min AND :date_param.max
```
輸入預設日期值，然後執行查詢來測試它。使用行事歷圖示來選擇預設選項，例如上周或上個月。

查詢型參數

查詢型參數可讓作者定義檢視者在探索儀錶板中數據時，可選擇的動態或靜態值清單。結合單一篩選小工具中的欄位篩選和參數篩選來定義它們。

若要建立查詢型參數，儀表板作者會執行下列步驟：

建立數據集，其結果集僅限於可能的參數值清單。
建立使用參數的資料集查詢。
在創作區設定篩選小工具，以篩選欄位並使用參數。
- Fields 設定應設為使用包含所需合格參數值列表的欄位。
- 參數配置應設定為選取參數值。

注意

如果儀表板上的其他視覺化圖表也使用了查詢參數中使用的數據集，則檢視者的篩選會修改所有已連接的查詢。為了避免這種情況，作者應該為儀錶板上任何其他視覺效果中未使用的查詢型參數建立專用數據集。

如需瞭解如何新增查詢型參數和視覺效果的逐步教學課程，請參閱查詢型參數的使用。

建立動態參數清單

若要建立動態數據集，以填入檢視者用來選取參數值的下拉式清單，請撰寫會傳回單一字段的 SQL 查詢，並包含該欄位中的所有值。該欄位中的任何新值都會自動新增為參數選取專案。 SQL 查詢範例如下所示：

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

建立靜態參數清單

您可以建立靜態資料集，只包含您硬編碼至資料集的值。查詢範例如下所示：

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

拿掉查詢參數

若要移除參數，請從查詢中刪除它。

靜態小工具參數會直接在視覺效果小工具中設定，讓作者能夠個別參數化共用相同數據集的視覺效果小工具。這可讓相同的數據集在畫布上呈現不同的檢視。

本節中的範例是以查詢 samples.nyctaxi.trips 數據表的數據集為基礎。提供的查詢會傳回每趟車程的距離，並將取貨日分類為 Weekday 或 Weekend。查詢參數會根據取貨發生在工作日或週末來篩選結果。

查詢文字會在下列程式代碼區塊中提供，但本節中的指示僅限於設定以靜態小工具參數設定的相關聯視覺效果。如需關於使用參數設定數據集的指示，請參閱將參數新增至查詢。


  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

若要將靜態小工具參數新增至視覺效果：

將視覺效果小工具新增至草稿儀表板創作區。
選取新的小工具後，從組態面板中的 [資料集] 下拉式清單中選擇參數化資料集。
按兩下 [ 顯示篩選]。針對包含參數的數據集，組態面板中會出現 Parameters 區段。
按兩下參數標題右邊的加號，然後從下拉式清單中選擇參數。
根據預設，參數值會反映在[數據]標籤頁的查詢中設定的值。您可以保留它，或選擇新的值來替換數據集中的值。瀏覽離開文字欄位以顯示已套用新參數的視覺效果。
檢閱您的儀表板。

下圖顯示兩個視覺效果小工具。每個都會設定為具有靜態小工具參數的直方圖。左側圖表會顯示從工作日開始之車程的車程距離分佈，而右邊的圖表則顯示週末的相同數據。這兩個視覺效果都基於相同的資料集。

使用篩選條件比較資料

您可以新增篩選條件，讓您比較數據部分的匯總與套用至整個數據集的匯總。

下列範例會擴充前一個查詢，以包含篩選條件，其中指定的參數值是 All，而不會出現在數據中。篩選條件的第一部分的運行方式與上一個範例相同，篩選出 day_type 為 Weekday 或 Weekend的結果。篩選條件的第二個部分會檢查參數本身是否設定為特定值，在此案例中為，All不會出現在數據中。當您在資料集編輯器中設定該參數的預設值時，當您未將 Weekday 或 Weekend 當做值傳入時，您實際上會略過篩選條件。


WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

您可以使用此數據集來設定三個視覺效果小工具，並將 day_type_param 分別設定為 All、Weekday 和 Weekend。然後，儀表板檢視者可以將依日類型篩選的每個數據集與整個數據集進行比較。

下列 GIF 示範如何從使用此查詢建立的資料集中快速建置三個圖表。

第一張圖表已配置為顯示依日類型的 車程距離 數據集，並將參數值設為平日。
複製圖表以維護所有已套用的組態。
若要顯示週末行程資料，請將靜態參數調整為 [週末]。
複製新的圖表，以維護所有先前套用的組態。
將新圖表中的參數設定為 [所有]，以顯示週末和平日按距離計算的總車程次數。

如上述文字中所述的 gif。

在儀錶板上顯示參數

將篩選新增至儀錶板畫布，可讓檢視者選取和修改參數值，以互動方式探索和分析數據。如果您未在儀錶板上公開參數，檢視者只會看到使用您在查詢中設定之預設參數值的查詢結果。

若要將參數新增至儀表板：

按一下 [新增篩選條件 (欄位/參數)]。
點擊 add field icon參數旁的 [新增欄位] 圖示。
按一下您想要檢視人員搭配此小工具使用的參數名稱。

使用篩選小工具與靜態參數

參數是在執行階段替換成查詢語句中的固定值。如果您的儀錶板更新時，使用相同參數的兩個或多個參考設定為不同的值，則視覺化元件會顯示錯誤訊息，指出哪個參數的值有衝突。當多個篩選器小工具使用相同的參數時或當靜態參數與允許檢視器選擇的篩選器小工具衝突時，可能會發生這種情況。

您可以使用類似下列範例中的模式，為相同查詢中的不同參數設定後援值。


CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

在此範例中，:static_param 參考靜態參數，這應該在視覺效果小工具與數據集編輯器中設定為『All』。參數 :dash_param 是由儀表板畫布上的篩選器小工具控制的動態值。此陳述式會檢查作為靜態參數提供的值。如果未設定任何值，則會回復為查看器選取的儀錶板參數值。

在 URL 中包含參數

參數設定會儲存在 URL 中，讓使用者將它加入書籤以維護其儀錶板的狀態，包括預先設定的篩選和參數，或與其他人共用，以一致地套用相同的篩選和參數。

儀錶板參數與 Mustache 查詢參數

儀錶板參數使用與具名參數標記相同的語法。請參閱具名參數標記。儀錶板不支援 Mustache 樣式參數。

語法範例

參數的常見用法包括插入 JSON 字串中的日期、數位、文字、資料庫物件和值。如需示範如何在這些情況下使用參數的範例，請參閱具名參數語法範例。

重要

啟用檢視者透過參數選擇例如數據表或目錄名稱來存取資料，可能會導致意外洩露敏感資訊。如果您要使用這些選項發佈儀錶板，Azure Databricks 建議不要在已發佈的儀錶板中內嵌認證。

共用方式為