查詢參數

發行項
03/01/2024

查詢參數可讓您在運行時間將值替換成查詢。雙大括弧 {{ }} 之間的任何字串都會被視為查詢參數。小工具會出現在結果窗格上方，您可以在其中設定參數值。查詢參數比查詢篩選更有彈性，而且應該只在查詢篩選不足的情況下使用。

新增查詢參數

輸入 Cmd + I。參數會插入文字插入號，且 [新增參數 ] 對話框隨即出現。
- 關鍵詞：代表查詢中參數的關鍵詞。
- 標題：出現在小工具上的標題。根據預設，標題與關鍵詞相同。
- 類型：支援的型別為文字、數位、日期、日期和時間、日期和時間（含秒）、下拉式清單和以查詢為基礎的下拉式清單。預設為 Text。
輸入關鍵詞，選擇性地覆寫標題，然後選取參數類型。
按兩下 [ 新增參數]。
在參數 Widget 中，設定參數值。
按兩下 [ 套用變更]。
按一下 [檔案] 。

或者，輸入雙大括弧 {{ }} ，然後按兩下參數小工具附近的齒輪圖示來編輯設定。

若要使用不同的參數值重新執行查詢，請在小工具中輸入值，然後按兩下 [ 套用變更]。

編輯查詢參數

若要編輯參數，請按兩下參數小工具旁邊的齒輪圖示。若要防止未擁有查詢的使用者變更參數，請按兩下 [ 僅顯示結果]。參數 <Keyword> 對話框隨即出現。

拿掉查詢參數

若要移除查詢參數，請從查詢中刪除參數。參數小工具消失，您可以使用靜態值重寫查詢。

變更參數的順序

若要變更顯示參數的順序，您可以按下每個參數，並將每個參數拖曳至所需的位置。

Text

接受字串做為輸入。反斜杠、單引號和雙引號都會逸出，而 Azure Databricks 會將引號新增至此參數。例如，類似的 mr's Li"s 字串會轉換成 'mr\'s Li\"s' 使用這個的範例可能是

SELECT * FROM users WHERE name={{ text_param }}

數值

接受數位作為其輸入。使用此範例可能是

SELECT * FROM users WHERE age={{ number_param }}

若要在執行查詢時限制可能的參數值範圍，請使用 下拉式清單 參數類型。 SELECT * FROM users WHERE name='{{ dropdown_param }}'例如。從參數設定面板選取時，會出現一個文字框，您可以在其中輸入允許的值，每一個值都會以新行分隔。下拉式清單是文字參數。若要在下拉式清單中使用日期或日期和時間，請以數據源所需的格式輸入它們。字串不會逸出。您可以選擇單一值或多重值下拉式清單。

單一值：需要參數周圍的單引號。
多重值：切換 [ 允許多個值] 選項。在 [ 引號 ] 下拉式清單中，選擇是否要將參數保留為輸入的（無引號）或以單引號或雙引號包裝參數。如果您選擇引號，則不需要在參數周圍加上引號。

將子 WHERE 句變更為在 IN 查詢中使用關鍵詞。

SELECT ...
FROM   ...
WHERE field IN ( {{ Multi Select Parameter }} )

參數多重選取小工具可讓您將多個值傳遞至資料庫。如果您為 [報價] 參數選取 [雙引號] 選項，則查詢會反映下列格式：WHERE IN ("value1", "value2", "value3")

接受查詢的結果作為其輸入。其行為與 下拉式清單 參數相同。您必須儲存 Databricks SQL 下拉式清單查詢，才能將它當做另一個查詢中的輸入。

按兩下 [設定] 面板中 [類型] 底下的 [查詢型下拉式清單]。
按兩下 [ 查詢] 欄位，然後選取查詢。如果您的目標查詢傳回大量記錄，效能將會降低。

如果您的目標查詢傳回一個以上的數據行，Databricks SQL 會使用第一個數據行。如果您的目標查詢傳 name 回和 value 數據行，Databricks SQL 會使用 name 資料行填入參數選取小工具，但會以相關聯的 value執行查詢。

例如，假設下列查詢會傳回數據表中的數據。

SELECT user_uuid AS 'value', username AS 'name'
FROM users

value	NAME
1001	John Smith
1002	Jane Doe
1003	Bobby 數據表

當 Azure Databricks 執行查詢時，傳遞給資料庫的值會是 1001、1002 或 1003。

日期與時間

Azure Databricks 有數個選項可將日期和時間值參數化，包括簡化時間範圍參數化的選項。從三個不同精確度的選項中選取：

選項	精確度	類型
日期	天	`DATE`
日期和時間	分鐘	`TIMESTAMP`
日期與時間（含秒）	second	`TIMESTAMP`

選擇 Range 參數選項時，您會建立由 .start 和 .end 後綴指定的兩個參數。所有選項都會將參數傳遞至查詢做為字串常值;Azure Databricks 會要求您將日期和時間值包裝在單引號中（'）。例如：

-- Date parameter
SELECT *
FROM usage_logs
WHERE date = '{{ date_param }}'

-- Date and Time Range parameter
SELECT *
FROM usage_logs
WHERE modified_time > '{{ date_range.start }}' and modified_time < '{{ date_range.end }}'

日期參數會使用行事曆挑選介面，並預設為目前的日期和時間。

注意

Date Range 參數只會傳回類型數據 DATE 行的正確結果。針對數據 TIMESTAMP 行，請使用其中一個 [日期和時間範圍] 選項。

動態日期和日期範圍值

當您將日期或日期範圍參數新增至查詢時，選取小工具會顯示藍色閃電圖示。點選此選項，則可以顯示動態值，例如today、yesterday、this week、、last weeklast month 或 last year。這些值會動態更新。

重要

動態日期和日期範圍與排程查詢不相容。

在儀錶板中使用查詢參數

或者，查詢可以使用參數或靜態值。將以參數化查詢為基礎的視覺效果新增至儀錶板時，可以將視覺效果設定為使用下列其中一項：

Widget 參數

小工具參數專屬於儀錶板中的單一視覺效果、出現在視覺效果面板中，而指定的參數值只會套用至視覺效果基礎的查詢。
儀錶板參數

儀錶板參數可以套用至多個視覺效果。當您根據參數化查詢將視覺效果新增至儀錶板時，參數預設會新增為儀錶板參數。儀錶板參數是針對儀錶板中的一或多個視覺效果所設定，並出現在儀錶板頂端。為儀錶板參數指定的參數值會套用至重複使用該特定儀錶板參數的視覺效果。儀錶板可以有多個參數，每個參數都可以套用至某些視覺效果，而不是其他視覺效果。
靜態值

靜態值會用來取代回應變更的參數。靜態值可讓您硬式編碼值來取代參數，並將參數從先前出現的儀錶板或小工具「消失」。

當您新增包含參數化查詢的視覺效果時，您可以按兩下適當的鉛筆圖示，選擇視覺效果查詢中參數的標題和來源。您也可以選取關鍵詞和預設值。請參閱參數屬性。

將視覺效果新增至儀錶板之後，單擊儀錶板小工具右上角的垂直省略號，然後按兩下 [ 變更小工具設定]，以存取參數對應介面。

參數屬性

標題：顯示在儀錶板上值選取器旁邊的顯示名稱。它預設為parameterKeyword。若要編輯它，請按下鉛筆圖示。靜態儀錶板參數不會顯示標題，因為值選取器已隱藏。如果您選取 [靜態值 ] 作為 [ 值來源]，[ 標題 ] 字段會呈現灰色。
關鍵詞：基礎查詢中此參數的字串常值。如果您的儀錶板未傳回預期的結果，這適用於偵錯。
預設值：如果未指定其他值，則使用的值。若要從查詢畫面變更此專案，請使用所需的參數值執行查詢，然後按兩下 [ 儲存 ] 按鈕。
值來源：參數值的來源。按兩下鉛筆圖示以選擇來源。
- 新的儀錶板參數：建立新的儀錶板層級參數。這可讓您在儀錶板的一個位置設定參數值，並將其對應至多個視覺效果。
- 現有的儀錶板參數：將參數對應至現有的儀錶板參數。您必須指定哪些預先存在的儀錶板參數。
- Widget 參數：在儀錶板小工具內顯示值選取器。這適用於在小工具之間未共用的一次性參數。
- 靜態值：不論在其他小工具上使用的值為何，都選擇小工具的靜態值。靜態對應的參數值不會在儀錶板上的任何位置顯示值選取器，更精簡。這可讓您利用查詢參數的彈性，而不需要在預期某些參數經常變更時，將儀錶板上的使用者介面雜亂無章。

常見問題集 (FAQ)

我可以在單一查詢中多次重複使用相同的參數嗎？
我可以在單一查詢中使用多個參數嗎？

我可以在單一查詢中多次重複使用相同的參數嗎？

是。在大括弧中使用相同的標識碼。這個範例會使用 {{org_id}} 參數兩次。

SELECT {{org_id}}, count(0)
FROM queries
WHERE org_id = {{org_id}}

我可以在單一查詢中使用多個參數嗎？

是。針對每個參數使用唯一的名稱。這個範例使用兩個參數： {{org_id}} 和 {{start_date}}。

SELECT count(0)
FROM queries
WHERE org_id = {{org_id}} AND created_at > '{{start_date}}'