什麼是儀錶板參數？

文章
06/25/2024

AI/BI 儀錶板參數是讓儀錶板互動的一種方式，可讓檢視者在運行時間使用單一值選取器和日期選擇器。例如，您可以在 SQL 查詢中匯總數據之前，使用參數根據日期和產品類別等準則來篩選數據，以便更有效率地查詢和精確分析。

參數會新增至數據集，並由儀錶板作者或編輯器連接到儀錶板畫布上的一或多個小工具。在運行時間選取篩選小工具中的值，儀錶板查看器會與儀錶板數據互動。這會重新執行相關聯的查詢，並呈現以篩選數據為基礎的視覺效果。

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

將參數新增至查詢

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

Gif 顯示下列步驟的範例。

若要將參數新增至查詢：

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

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

編輯查詢參數

若要編輯參數：

點選參數名稱旁的。 [ 參數詳細數據 ] 對話框隨即出現，並包含下列組態選項：
- 關鍵詞：代表查詢中參數的關鍵詞。這隻能藉由直接更新查詢中的文字來變更。
- 顯示名稱：篩選編輯器中的名稱。根據預設，標題與關鍵詞相同。
- 類型：支持的類型包括 String、Date、Date 和 Time、Numeric。
  - 默認類型為 String。
  - Numeric 數據類型可讓您在 Decimal 和 Integer 之間指定。預設數值類型為 Decimal。
按兩下UI的另一部分以關閉對話框。

設定預設參數值

您可以在參數名稱下的文字欄位中輸入參數，以設定參數的預設值。執行查詢，以預覽套用參數值的查詢結果。執行查詢也會儲存預設值。當您在畫布上使用篩選小工具設定此參數時，會使用預設值。

查詢型參數

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

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

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

注意

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

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

建立動態參數清單

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

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

建立靜態參數清單

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

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

篩選類型

單一值 和 日期選擇器 篩選支援設定參數。使用 日期選擇器 篩選設定查詢型參數時，基礎查詢結果中顯示的日期會以黑色顯示。查詢結果中未出現的日期為灰色。即使基礎查詢中未包含灰色日期，用戶還是可以選擇灰色日期。

拿掉查詢參數

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

在儀錶板上顯示參數

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

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

按兩下 [新增篩選條件][欄位/參數]。
按兩下組態面板中的 [參數] 旁。
按下您想要查看器搭配此小工具使用的參數名稱。

在 URL 中包含參數

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

參數語法範例

下列範例示範參數的一些常見使用案例。

插入日期

下列範例包含 Date 參數，將查詢結果限制在特定日期之後的記錄。


SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY
  1,
  2

插入數位

下列範例包含 Numeric 參數，將結果限製為欄位大於所提供參數值的記錄 o_total_price 。


SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

插入功能變數名稱

在下列範例中， field_param 會與函 IDENTIFIER 式搭配使用，在運行時間提供查詢的臨界值。參數值應該是查詢中所用數據表的數據行名稱。


SELECT
  *
FROM
  samples.tpch.orders
WHERE
  IDENTIFIER(:field_param) < 10000

插入資料庫物件

下列範例會建立三個參數： catalog、 schema和 table。儀錶板檢視者可以使用畫布上的篩選小工具來選取參數值。


SELECT
  *
FROM
  IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

請參閱 IDENTIFIER子句。

重要

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

串連多個參數

您可以在其他 SQL 函式中包含參數。此範例可讓查看器選取員工職稱和數位標識碼。查詢會使用函 format_string 式串連兩個字串，並篩選相符的數據列。請參閱 format_string 函式。


SELECT
  o_orderkey,
  o_clerk
FROM
  samples.tpch.orders
WHERE
  o_clerk LIKE format_string('%s%s', :title, :emp_number)

儀錶板參數與 Databricks SQL 查詢參數

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

分享方式：