使用儀表板參數

發行項
11/15/2024

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

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

儀表板作者或編輯人員可將參數新增至資料集，並將它們連接到儀表板創作區的一個或多個小工具。針對在視覺效果小工具中設定的靜態參數，這些值由作者或編輯人員設定。針對篩選小工具中使用的參數，儀表板檢視人員可以在執行階段選取篩選小工具中的值來與資料互動。此互動會重新執行相關聯的查詢，並根據篩選的資料顯示視覺效果。

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

將參數新增至查詢

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

Gif 顯示以下步驟的範例。

若要將參數新增至查詢：

將資料指標放在想要在查詢中放置參數的位置。
按下 [新增參數]即可插入新參數。

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

編輯查詢參數

若要編輯參數：

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

設定預設參數值

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

允許多個選取專案

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

下列範例顯示 SQL 查詢，可讓您選取多個值，以在運行時間插入查詢中。子句會使用函WHEREARRAY_CONTAINS式。該函式會採用參數關鍵詞和數據行名稱作為自變數。當查詢執行時，它會傳回包含所選參數值的所有數據列。

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

若要設定預設值，請在顯示名稱下方的文字欄位中輸入它們。輸入下一個值之前，請先選取目前的值。

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

套用日期範圍參數

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

日期範圍
日期和時間範圍

下列範例顯示建立名為 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
```
輸入預設日期值，然後執行查詢來測試它。使用行事歷圖示來選擇預設選項，例如上周或上個月。

查詢型參數

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

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

建立資料集，其結果集僅限於可能的參數值清單。
建立使用參數的資料集查詢。
在創作區設定篩選小工具，以篩選欄位並使用參數。
- [欄位] 組態應設定為使用具有所需合格參數值清單的欄位。
- [參數] 組態應設定為選取參數值。

注意

如果查詢型參數中使用的資料集也用於儀表板的其他視覺效果中，則檢視人員的篩選條件選取會修改所有已連線的查詢。為了避免這種情況，作者應該為儀表板上任何其他視覺效果中未使用的查詢型參數建立專用資料集。

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

建立動態參數清單

若要建立動態資料集，以填入檢視者用來選取參數值的下拉式清單，請撰寫會傳回單一欄位並在該欄位中包含所有值的 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

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

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

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

使用篩選條件比較資料

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

下列範例會擴充前一個查詢，以包含篩選條件，其中指定的參數值為 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。

在儀表板中顯示參數

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

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

按一下 [新增篩選條件 (欄位/參數)]。
按一下組態面板中 [參數] 旁邊的。
按一下您想要檢視人員搭配此小工具使用的參數名稱。

使用篩選器小工具和靜態參數

參數是在執行階段取代為查詢的固定值。如果在儀表板更新時對同一參數的兩個或多個參考設定了不同的值，則視覺效果小工具將顯示錯誤，指示哪個參數含有衝突的值。當多個篩選器小工具使用相同的參數時或當靜態參數與允許檢視器選擇的篩選器小工具衝突時，可能會發生這種情況。

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


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

在此範例中，:static_param 指的是靜態參數，在視覺效果小工具和資料集編輯器中都應將其設定為 [全部]。參數 :dash_param 是由儀表板畫布上的篩選器小工具控制的動態值。此陳述式會檢查作為靜態參數提供的值。如果未設定任何值，則將回復為檢視器選取的儀表板參數值。

在 URL 中包含參數

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

儀表板參數與 Mustache 查詢參數

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

語法範例

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

重要

讓檢視人員能夠透過資料表或目錄名稱等參數選取來存取資料，可能會導致不小心暴露敏感性資訊。如果您要發佈具有這些選項的儀表板，Azure Databricks 建議不要在已發佈的儀表板中內嵌認證。

共用方式為