預留位置 - Quick BI

本文主要為您介紹預留位置的使用情境和使用方法。

操作步驟

建立入口

入口一：自訂SQL編輯頁面

在SQL代碼編輯頁面，單擊預留位置管理。
在預留位置管理面板，系統會自動識別您在SQL中使用的預留位置並展示在預留位置管理面板中，您可以對預留位置的變數類型、預設值進行修改，配置完成後單擊確定。

入口二：資料處理介面

在資料處理介面的工具列裡，單擊建立預留位置，輸入變數名、變數類型和查詢預設值後單擊確定。
當資料集存在預留位置時，您可以單擊欄位大綱->預留位置右側的表徵圖，進入預留位置管理介面。在預留位置管理介面，單擊建立預留位置，通過手動輸入的方式建立預留位置。

入口三：儀表板編輯頁面

在儀表板編輯頁面，按照以下方式建立預留位置。
1. 單擊表徵圖，建立預留位置。
2. 在預留位置管理介面建立預留位置。
在建立預留位置介面輸入變數名、變數類型和查詢預設值。

配置項及說明

配置項	說明
變數名	預留位置的名稱，可自訂修改。
類型	預留位置的類型，分為運算式預留位置、值預留位置和加速預留位置，類型不支援修改。
變數類型	支援文本、數值、日期-年、日期-年季、日期-年月、日期-年周、日期-年月日、日期-年月日時分秒。
查詢預設值	預設值生效範圍支援僅資料集和全域生效兩種模式：僅資料集：只在資料集編輯頁生效。說明加速預留位置的查詢預設值為僅資料集，且不支援修改。全域生效：在儀表板、試算表等下遊也生效。輸入框輸入最多150個字元。說明運算式預留位置的預設值需填寫完整的運算式，比如：area = "東北"。
操作	單擊表徵圖刪除預留位置。

值預留位置

可通過儀表板上的查詢控制項傳入一個值、一組值。

說明

當預留位置是日期時，需要選擇具體的日期格式，來控制傳入值的格式。

格式：'$val{預留位置名}'

SQL程式碼範例如下：

SELECT * FROM tablename
WHERE area in ('$val{area_ph}') -- 文本類型 多選
AND name = '$val{name_ph}' -- 文本類型 單選
AND number = $val{number_ph} -- 數實值型別
AND report_date > '$val{report_date_ph.get(0)}' -- 日期類型 擷取日期範圍控制項起始日期
AND report_date < '$val{report_date_ph.get(1)}' -- 日期類型 擷取日期範圍控制項結束日期

運算式預留位置

可通過儀表板上的查詢控制項傳入一個條件。

當儀表板上的篩選條件中，使用者可以自由修改篩選方式，需要使用運算式預留位置，將整個篩選條件都傳入SQL。

格式：$expr{物理欄位名:預留位置名}

SQL程式碼範例如下：

SELECT report_date,
 order_level,
 shipping_type,
 area,
 price,
 order_number
from company_sales_record
where $expr{report_date :report_date}
and $expr{order_level :order_level}
and $expr{order_number :order_number}

標籤預留位置

通過標籤預留位置擷取當前訪問使用者的標籤值。

格式： $tag{使用者標籤名}

例如，控制某員工只能看到華北大區的資料，只能看到商品A，商品B的資料，則配置某使用者的標籤：

地區：華北
商品：商品A, 商品B

SQL程式碼片段樣本：

select * from table_name
where 
area = '$tag{地區}'
and
product in ('$tag{商品}')

當某使用者訪問資料時，系統會自動讀取該使用者的標籤，運行時的SQL樣本。

select * from table_name
where 
area = '華北'
and
product in ('商品A', '商品B')

系統預留位置

使用方法和其他預留位置一致，能夠用在SQL、計算欄位中，支援以下4種系統預留位置：

使用者名稱（登入帳號）：$system{accountName}
使用者暱稱（組織內）：$system{userNick}
使用者ID（Quick BI系統內）：$system{userId}
三方系統使用者ID（阿里雲ID）：$system{accountId}

SQL樣本如下：

select
  *
from
  company_sales_record
where
  customer_name = '$system{accountName}'
  and customer_name = '$system{userNick}'

條件預留位置

可通過儀表板上的樹形下拉查詢控制項傳入一組值。

格式：'$condition{一級欄位, 二級欄位: 預留位置名}'

其中，欄位數量最多限制10個，需要和查詢控制項樹形結構保持一致。

SQL樣本如下：

select
 *
from
 company_sales_record
where 
 $condition{product_type,product_sub_type,product_name :product_para}

查詢控制項配置如下：

加速預留位置

加速預留位置用於抽取加速，適配自訂 SQL 中包含時間參數的情境。通過在 WHERE 條件中放置加速預留位置，Quick 引擎可在抽取階段動態替換時間視窗，並按配置進行增量離線抽取。

格式：$accel{物理欄位名:預留位置名}

SQL樣本如下：

select
  *
from
  company_sales_record
where
  $accel{report_date:report_date}

說明

僅加速預留位置支援 Quick 引擎的抽取加速；其他預留位置類型暫不支援抽取加速。
每個資料集當前僅支援添加 1 個加速預留位置。
不支援在計算欄位中使用加速預留位置。
加速預留位置僅在資料集層生效（用於自訂 SQL 運行與加速抽取）；在圖表查詢中不生效，查詢控制項中也不展示該預留位置。

查詢預設值：為避免自訂SQL運行逾時，此處可為加速預留位置設定預設值。

樣本：加速預留位置的預設值需為完整的過濾運算式，而非單獨的日期值，例如report_date<'2025-04-01'

加速配置：對於已添加加速預留位置的資料集，可在加速配置的日期欄位中選擇該預留位置欄位，設定抽取時間範圍與增量粒度，完成加速任務的配置。

應用情境

情境1-動態調整計算欄位結果值

情境描述

設定計算欄位，並在運算式中引用預留位置，通過傳預留位置的值調整計算欄位的值。

如：超過預留位置值的為大訂單，否則為小訂單；可通過查詢控制項傳預留位置值，動態調整大訂單和小訂單的衡量標準，圖表也隨之重新整理。

操作步驟

建立預留位置。
1. 在自訂SQL編輯頁或資料集編輯頁單擊預留位置管理->建立預留位置。
2. 輸入變數名Price，類型為值預留位置，變數類型為數值，查詢預設值為全域生效，預設值為100（選填）。
  說明
  用到計算欄位的預留位置必須有全域生效的預設值。
建立計算欄位。
1. 在資料集編輯頁面，單擊建立欄位，按照圖示方式建立訂單規模欄位。
  欄位運算式樣本：
```
case when [price]>$val{Price}
then '大訂單'
else '小訂單'
end
```
2. 單擊確定並儲存資料集。
建立可視化圖表和查詢控制項。
1. 單擊開始分析->建立儀表板。
2. 在儀表板編輯頁面，按照圖示方式添加柱圖。
3. 將訂單規模欄位拖入類別軸/維度，將price欄位拖入值軸/度量，並單擊更新，此時柱圖展示效果如下：
  此時，我們可以看到，度量欄位price按照佔位符Price的預設值100，區分出大訂單和小訂單。
4. 按照圖示方式建立查詢控制項。
5. 在查詢條件設定介面，將佔位符Price設定為查詢條件。
查看效果。
此時，您可以通過輸入查詢控制項的數值來調整大小訂單的衡量標準。
比如查詢控制項數值為100時，大訂單金額為60.72萬；查詢控制項數值為150時，大訂單金額為52.5萬。

情境2-靈活切換指標或分析維度

情境描述

當您有多個指標、維度需要展示，但放在同一個圖表會顯得內容較多不夠清晰，搭建多個圖表又會導致內容冗餘時，可通過該能力實現圖表欄位的靈活切換。

以切換指標維度為例。

操作步驟

建立預留位置。
1. 在自訂SQL編輯頁或資料集編輯頁單擊預留位置管理->建立預留位置。
2. 輸入變數名指標，類型為值預留位置，變數類型為文本，查詢預設值為全域生效，預設值為單價。

建立計算欄位。

單擊建立欄位，按照圖示方式建立資料欄位。

欄位運算式樣本：

case when '$val{指標}'='訂單金額' then [訂單金額]
when '$val{指標}'='利潤金額' then [利潤金額]
when '$val{指標}'='單價' then [單價]
when '$val{指標}'='運輸成本' then [運輸成本]
else 0
end

說明

文本類型預留位置請用英文單引號引用，例如'$val{指標}'。

單擊確定並儲存資料集。

建立可視化圖表和查詢控制項。
1. 單擊開始分析->建立儀表板。
2. 在儀表板編輯頁面，按照圖示方式添加柱圖。
3. 將地區欄位拖入類別軸/維度，將資料段拖入值軸/度量，並單擊更新，此時柱圖展示效果如下：
4. 按照圖示方式建立查詢控制項。
5. 在查詢條件設定介面，將佔位符指標設定為查詢條件，選項值來源選擇手工輸入並配置手工錄入的值。
查看效果。
此時，您可以通過篩選查詢控制項的值切換不同的指標。

情境3-動態調整輔助線

情境描述

將輔助線的值與預留位置綁定，為預留位置賦值時，輔助線跟隨變化。

如：輔助線為每月的銷售額KPI，每個月只需要通過查詢控制項調整即可動態更新輔助線的位置，不需要重新修改報告。

操作步驟

建立預留位置。
說明
輔助線裡的預留位置只支援數實值型別。
1. 在儀表板編輯頁面，按照圖示方式建立預留位置。
2. 輸入變數名Target，變數類型為數值，查詢預設值為全域生效，預設值為4000000。
  說明
  輔助線中使用的預留位置必須有全域生效的預設值。
設定輔助線。
1. 在分析頁簽，找到輔助線並單擊右側筆形表徵圖。
2. 按照圖示方式設定添加輔助線，並設定值為預留位置Target。
  此時您可以看到輔助線400萬顯示在圖表上。
建立查詢控制項。
1. 按照圖示方式建立查詢控制項。
2. 設定預留位置Target為查詢條件並單擊確定。
查看效果。
您可以通過切換查詢控制項的值來調整輔助線的位置。

情境4-SQL代碼中使用預留位置實現欄位結果值的動態調整以及過濾

情境描述

用SQL代碼建立資料集時,代碼中引用預留位置，通過調整預留位置的值實現欄位結果值的動態調整以及過濾。

操作步驟

在資料集編輯頁面，單擊畫布中的點擊使用SQL代碼建立資料集或左側面板中的SQL代碼建立表。

輸入SQL代碼後

SQL樣本如下：

SELECT report_date, order_level, shipping_type,price,order_number,area,
 case when profit_amt< ${profit_range} then'虧損' 
 when profit_amt> ${profit_range} then'盈利'
 else '持平'
 end '訂單等級'
from company_sales_record
where $expr{report_date :report_date}
and $expr{order_level :order_level}
and $expr{order_number :order_number}

單擊預留位置管理。
進入預留位置管理介面並輸入預設值。
說明
如果預留位置應用在select語句後面，必須設定全域生效的預設值。
本例中，預留位置“profit_range”必須設定全域生效的預設值。
單擊運行，可以看到運行結果。
單擊確認編輯並儲存資料集。
建立可視化圖表和查詢控制項。
1. 單擊開始分析->建立儀表板。
2. 在儀表板編輯頁面，按照圖示方式添加餅圖。
3. 按照圖示方式建立查詢控制項。
4. 查看效果
  此時，您可以通過輸入查詢控制項的數值來調整利潤範圍的衡量標準。

情境5-對包含加速預留位置的資料集開啟抽取加速

情境描述

通過在自訂 SQL 的 WHERE 條件中引入加速預留位置，並在加速配置中設定分區大小，實現資料的動態離線抽取與增量寫入。適用於底表資料量大，原先自訂 SQL 運行逾時，無法配置抽取加速的情況。

操作步驟

建立預留位置。
在自訂SQL的 WHERE 條件中，添加加速預留位置。
您只需要關注核心的查詢邏輯，時間過濾交給預留位置處理。
樣本：在 WHERE 條件中加入report_date加速預留位置：where $accel{report_date:report_date}。
設定查詢預設值。
為了讓SQL在編輯和預覽階段能夠快速運行，需要為預留位置設定一個預設值。
您可以在資料集的預留位置管理中，為加速預留位置設定完整運算式作為預設值，例如：report_date < '2025-04-01'。
配置抽取加速。
Data Integration功儲存後，您可以配置抽取加速。
1. 開啟Quick 引擎。
2. 抽取範圍選擇指定日期範圍並選擇日期欄位為該加速預留位置對應的欄位（如 report_date）。
3. 配置抽取日期範圍、增量範圍等，儲存並啟動加速任務。
驗證查詢與加速效果
1. 使用該資料集建立圖表進行查詢。
2. 在圖表的效能診斷頁查看組件載入時間長度與組件載入詳情中的加速引擎是否開啟，確認加速生效。