本頁面說明 dashboard.lkml 檔案中，與 type: single_value 的 LookML 資訊主頁元素搭配使用的參數。
如要瞭解如何透過 Looker UI 建立單一值圖表，請參閱「KPI (單一值) 圖表選項」或「單一值 (舊版) 圖表選項」說明文件頁面。
基本參數
定義 LookML 資訊主頁元素時，您必須至少指定 name 和 type 參數的值。其他基本參數 (例如 title、height 和 width) 會影響資訊主頁中元素的位置和外觀。
name
本節說明資訊主頁元素中的
name參數。
name也可以做為資訊主頁篩選器的一部分，詳情請參閱「資訊主頁參數」說明文件頁面。
每個 name 宣告都會建立新的資訊主頁元素，並指派名稱。元素名稱不得重複。使用 layout: grid 資訊主頁時，名稱有時會出現在 elements 參數中；將元素整理成圖塊群組 (type: group) 時，名稱則會出現在子元素的 group 參數中。
- name: orders_by_date
title
本節說明資訊主頁元素中的
title參數。
title也可以做為資訊主頁的一部分，詳情請參閱「資訊主頁參數」說明文件頁面。
title也可以做為資訊主頁篩選器的一部分，詳情請參閱「資訊主頁參數」說明文件頁面。
title 參數可讓您變更元素名稱向使用者顯示的方式。如未指定，標題會預設為 name 元素。
請參閱以下範例：
- name: sales_overview
title: '1) Sales Overview'
如果使用這種格式，元素就不會顯示為「銷售總覽」，而是「1) 銷售總覽」。
type
本節說明資訊主頁元素中的
type參數。
type也可以做為資訊主頁篩選器的一部分，詳情請參閱「資訊主頁參數」說明文件頁面。
type也可以做為彙整的一部分，詳情請參閱type(用於彙整) 參數說明文件頁面。
type也可以做為維度的一部分，詳情請參閱「維度、篩選器和參數類型」說明文件頁面。
type也可以做為測量指標的一部分，詳情請參閱「測量指標類型」說明文件頁面。
type 參數會決定元素中使用的圖表類型。
- name: element_name
type: text | looker_grid | table | single_value | looker_single_record |
looker_column | looker_bar | looker_scatter | looker_line | looker_area |
looker_pie | looker_donut_multiples | looker_funnel | looker_timeline |
looker_map | looker_google_map | looker_geo_coordinates | looker_geo_choropleth |
looker_waterfall | looker_wordcloud | looker_boxplot | button | group
如要概略瞭解不同類型的 LookML 資訊主頁元素，請參閱 type (適用於 LookML 資訊主頁) 說明文件頁面。
height
本節說明資訊主頁元素中的
height參數。
height也可以做為資訊主頁資料列的一部分，詳情請參閱資訊主頁參數說明文件頁面。
適用於採用 tile 或 static 版面配置的資訊主頁
height 參數定義元素的高度，單位為 tile_size (以像素定義)，適用於 layout: tile 和 layout: static 資訊主頁。
舉例來說，下列程式碼指定 tile_size: 100 和 height: 4，將 orders_by_date 元素的高度設為 400 像素。
- dashboard: sales_overview
tile_size: 100
...
elements:
- name: orders_by_date
height: 4
...
適用於採用newspaper版面配置的資訊主頁
height 參數定義 layout: newspaper 資訊主頁中元素的高度，單位為列。
採用新聞版面配置的資訊主頁，預設元素高度為 6 列，約 300 像素。如果資訊主頁的 preferred viewer 參數設為 dashboards-next，則高度下限為 1 列。如果資訊主頁的 preferred viewer 參數設為 dashboards，則高度下限為 2 列。
舉例來說，下列程式碼會將元素設為 12 列高，或設為預設值的其他元素高度的兩倍：
- dashboard: sales_overview
layout: newspaper
...
elements:
- name: orders_by_date
height: 12
...
width
本節說明資訊主頁元素中的
width參數。
width也可以做為資訊主頁的一部分，詳情請參閱「資訊主頁參數」說明文件頁面。
width 參數定義元素的寬度，單位為 tile_size，適用於 layout: tile 和 layout: static 資訊主頁。
舉例來說，下列程式碼指定 tile_size: 100 和 width: 4，讓 orders_by_date 元素的寬度為 400 像素。
- dashboard: sales_overview
tile_size: 100
...
elements:
- name: orders_by_date
width: 4
...
width 參數定義 layout: newspaper 資訊主頁中元素的寬度，單位為欄。
採用報紙版面配置的資訊主頁預設寬度為 24 欄。
舉例來說，下列程式碼會將元素設為資訊主頁寬度的一半：
- dashboard: sales_overview
layout: newspaper
...
elements:
- name: orders_by_date
width: 12
...
top
top 參數定義元素由上至下的位置，單位為 tile_size，適用於 layout: static 資訊主頁。
舉例來說，下列程式碼指定 tile_size: 100 和 top: 4，將 orders_by_date 元素的頂端邊緣定位在距離資訊主頁頂端 400 像素的位置。
- dashboard: sales_overview
tile_size: 100
...
elements:
- name: orders_by_date
top: 4
...
left
left 參數定義元素由左至右的位置，單位為 tile_size，適用於 layout: static 資訊主頁。
舉例來說，下列程式碼指定 tile_size: 100 和 left: 4，將 orders_by_date 元素的左側邊緣定位在距離資訊主頁左側 400 像素的位置。
- dashboard: sales_overview
tile_size: 100
...
elements:
- name: orders_by_date
left: 4
...
row
如果是 layout: newspaper 資訊主頁，row 參數會定義元素頂端邊緣所在的列。如果使用 group 參數將元素放置在圖塊群組中，row 會定義元素相對於群組容器頂端 (row: 0) 的列位置。
資訊主頁頂端為第 0 列。新聞版面配置資訊主頁的預設元素高度為 6 列，也就是說，資訊主頁頂端的資訊主頁元素 (row: 0) 預設會占用第 0 到 5 列。
每列高 50 像素，因此預設元素高度為 6 列，即 300 像素。
舉例來說，假設元素設為預設高度，下列程式碼會將元素設在資訊主頁的第二列元素：
- dashboard: sales_overview
layout: newspaper
...
elements:
- name: orders_by_date
row: 6
...
col
如果是 layout: newspaper 資訊主頁，col 參數會定義元素左側邊緣所在的資料欄。如果使用 group 參數將元素放在圖塊群組中，col 會定義元素相對於群組容器左側邊緣 (col: 0) 的欄位置。
資訊主頁分為 24 欄。資訊主頁從左側的第 0 欄開始。報紙版面配置的資訊主頁預設元素寬度為 8 欄，也就是說，資訊主頁左側的資訊主頁元素 (col: 0) 預設會占用第 0 到 7 欄。
舉例來說，下列程式碼會將元素設為資訊主頁中第三欄的元素：
- dashboard: sales_overview
layout: newspaper
...
elements:
- name: orders_by_date
col: 16
...
refresh
本節說明資訊主頁元素中的
refresh參數。
refresh也可以做為資訊主頁的一部分，詳情請參閱「資訊主頁參數」說明文件頁面。
refresh 參數可讓元素定期自動重新載入，藉此擷取最新資料。如果資訊主頁會持續顯示 (例如在辦公室電視上)，這項功能通常很有幫助。請注意，您必須在瀏覽器視窗中開啟資訊主頁，這個參數才會生效。這項設定不會在背景執行，以「預熱」資訊主頁快取。
重新整理頻率可以設為任何數字 (不含小數)，單位為秒、分、時或天。例如：
- name: orders_by_date
refresh: 2 hours
設定較短的重新整理間隔時，請務必謹慎。如果元素背後的查詢需要大量資源，某些元素可能會對資料庫造成過大負擔。
note
您可以為元素加上說明備註，如下所示：
- name: element_name
note:
text: 'note text'
state: collapsed | expanded
display: above | below | hover
note 包含子參數 text、state 和 display。
text
text 子參數會指定附註中顯示的文字。文字可以本地化。
state
state 子參數會決定附註是否會collapsed或expanded (如果附註太大，無法在元素寬度內顯示在單一列中)。如果選擇「collapsed」，且附註過長，附註結尾會顯示可點選的刪節號 (...)，點選後即可閱讀完整附註。
display
display 子參數會決定附註在元素上的顯示位置。above 會將附註放在元素頂端，below 會將附註放在元素底部，hover 則需要使用者將滑鼠游標懸停在元素上，才能看到附註。
查詢參數
定義 LookML 資訊主頁元素時，您必須至少指定 model 和 explore 查詢參數的值，且至少須使用 dimensions 參數或 measures 參數指定一個欄位。您也可以使用其他查詢參數，控管資訊主頁元素中的資料顯示方式。
model
model 參數定義了元素查詢要使用的模型。如未指定，則預設為資訊主頁所在的模型。
- name: orders_by_date
model: ecommerce
model 參數接受 LookML 常數。您可以在專案的資訊清單檔案中定義常數，然後使用 "@{constant_name}" 語法將常數設為 model 的值。使用常數可讓您在一個地方定義模型名稱，如果有多個資訊主頁元素使用同一個模型，而您要更新模型名稱，這個方法特別實用。
如需更多資訊和 LookML 資訊主頁使用常數的範例，請參閱 constant 參數說明文件頁面。
explore
本節說明資訊主頁元素中的
explore參數。
explore也可以做為模型的一部分，詳情請參閱explore參數說明文件頁面。
explore也可以做為資訊主頁篩選器的一部分，詳情請參閱「資訊主頁參數」說明文件頁面。
explore 參數定義了要用於元素查詢的探索。
- name: orders_by_date
explore: order
explore 參數接受 LookML 常數。您可以在專案的資訊清單檔案中定義常數，然後使用 "@{constant_name}" 語法將常數設為 explore 的值。使用常數可讓您在一個位置定義探索名稱，如果有多個資訊主頁元素使用同一個探索，而您要更新該探索的名稱，這個方法就特別實用。
如需更多資訊和 LookML 資訊主頁使用常數的範例，請參閱 constant 參數說明文件頁面。
dimensions
dimensions 參數定義了元素查詢要使用的維度。使用 view_name.dimension_name 語法指定維度。如果查詢沒有任何 dimensions，請勿加入。
## single dimension example
- name: orders_by_date
dimensions: order.order_date
## multiple dimension example
- name: orders_by_date
dimensions: [order.order_date, customer.name]
measures
measures 參數定義了元素查詢要使用的測量指標。請使用 view_name.measure_name 語法指定測量指標。如果查詢沒有任何 measures，請勿加入。
## single measure example
- name: orders_by_date
measures: order.count
## multiple measure example
- name: orders_by_date
measures: [order.count, order_item.count]
sorts
sorts 參數會定義元素查詢的排序行為。請先列出主要排序欄位，再列出次要排序欄位。使用 view_name.field_name 語法指定要排序的維度或測量指標。
如果省略 sorts 參數，元素會使用 Looker 的預設排列順序。遞增排序不需要後置字串，遞減排序則需要 desc 後置字串。
以下範例定義了單一排序：
- name: orders_by_date
sorts: order.order_date desc
以下範例定義了多個排序：
- name: orders_by_date
sorts: [order.order_date desc, customer.name]
如果透視維度，您可以指定指標名稱、排序方向，以及資料表中目標資料欄的 0 索引編號，藉此排序查詢結果。舉例來說，下列元素會使用索引 0，依第一個資料透視欄排序：
- name: orders_by_category
sorts: [orders.count desc 0]
如要依資料列總計排序，請指定總計欄的索引。舉例來說，下列元素會使用索引 2 依資料列總數排序，代表含有兩個資料透視欄的查詢總數欄：
- name: orders_by_cohort
sorts: [users.count desc 2]
pivots
pivots 參數定義了應為元素查詢透視的維度。使用 view_name.dimension_name 語法指定維度。如果查詢沒有任何 pivots，請勿加入。
## single pivot example
- name: orders_by_date
pivots: customer.gender
## multiple pivot example
- name: orders_by_date
pivots: [customer.gender, customer.age_tier]
limit
limit 參數定義了元素查詢應使用的資料列限制。這項限制適用於套用任何資料透視之前的資料列數量。
- name: orders_by_date
limit: 100
filters
本節說明資訊主頁元素中的
filters參數。
filters也可以做為資訊主頁的一部分，詳情請參閱「資訊主頁參數」說明文件頁面。
filters也可以做為測量指標的一部分，詳情請參閱filters參數說明文件頁面。
filters 參數定義了元素查詢應使用的不可變更篩選條件。如要讓使用者可以在資訊主頁中變更篩選器，請使用資訊主頁的 filters 設定篩選器，然後使用 listen 將篩選器套用至元素。
filters 的語法如下：
- name: element_name
filters:
orders.created_date: 2020/01/10 for 3 days
orders.status: Shipped
# You can create multiple filter statements
每個篩選器都能接受 Looker 篩選運算式或值常數。您也可以在篩選運算式中使用 _localization 或 _user_attributes Liquid 變數，彈性設定篩選值。
listen
檢視者可透過資訊主頁篩選器，以互動方式調整資訊主頁元素中顯示的資料。使用 LookML 資訊主頁的 filters 參數定義資訊主頁篩選器。接著，使用 listen 參數將資訊主頁元素連結至資訊主頁篩選器。
listen 的語法如下：
- name: element_name
listen:
filter_name_goes_here: dimension or measure on which to apply
the filter using view_name.field_name syntax
# You can add more than one listen statement
請在元素中加入 listen 參數，然後提供篩選器名稱，後面加上冒號，並使用 view_name.field_name 語法參照要套用篩選器的欄位。舉例來說，您可以建立名為「日期」的篩選器，要求使用者在 UI 的篩選器欄位中輸入日期。接著，您可以將使用者輸入的值套用至 orders_by_date 元素，如下所示：
- dashboard: sales_overview
...
filters:
- name: date
type: date_filter
elements:
- name: orders_by_date
listen:
date: order.order_date
...
如果監聽的篩選器已設定 vis_filter: true 參數，篩選器控制項會直接顯示在圖表圖塊頂端的篩選器列中，而非資訊主頁頂端的篩選器列。
如需更多範例，瞭解如何使用 filters 參數和 listen 參數，將資訊主頁篩選器套用至個別資訊主頁元素，請參閱「建構 LookML 資訊主頁」。
query_timezone
query_timezone 參數會指定執行查詢的時區。時區選項會顯示在「timezone 的值」說明文件頁面。如要使用檢視者的時區執行查詢，可以將值指派為 user_timezone。
- name: orders_by_date
query_timezone: America/Los Angeles
- name: orders_by_customer
query_timezone: user_timezone
merged_queries
merged_queries 參數可讓您將多個查詢的結果合併為單一資訊主頁元素。在元素的 merged_queries 參數中定義每個來源查詢，並使用 join_fields 子參數指定結果合併方式。
以下 LookML 程式碼範例會建立type: looker_grid 的合併結果元素。在這個範例中，merged_queries 參數用於建立資訊主頁元素，將兩項獨立查詢的資料合併為單一表格圖表：
- name: merged_results_element
title: Merged Results Tile
type: looker_grid
merged_queries:
- model: ecommerce
explore: users
type: table
fields: [users.state, users.count, users.city]
sorts: [users.count desc 0]
limit: 5000
column_limit: 50
query_timezone: UTC
listen:
- State: users.state
- model: ecommerce
explore: users
type: table
fields: [users.state, users.city]
sorts: [users.state]
limit: 500
column_limit: 50
query_timezone: UTC
join_fields:
- field_name: users.state
source_field_name: users.state
- field_name: users.city
source_field_name: users.city
listen:
- State: users.state
在這個範例中，資訊主頁元素會合併兩個來源查詢的資料，這些查詢是以 ecommerce 模型中的 users 探索為基礎。主要查詢包含 users.state、users.count 和 users.city 欄位，並依 users.count 欄位排序結果。第二個來源查詢包含 users.state 和 users.city 欄位，並依 users.state 欄位排序結果。
join_field 參數會根據 users.state 和 users.city 欄位中的相符值，合併來源查詢。
listen 參數會將 State 篩選器套用至兩項查詢，讓資訊主頁檢視者選取特定州別，精細調整資訊主頁圖塊中顯示的查詢結果。
範例：合併公司資料
假設您想建立合併查詢，整合來自兩個不同探索 (company_info 和 companies) 的公司資訊。您想在每個探索的 ipo.stock_symbol、companies.name 和 companies.contact_email 欄位上彙整查詢，建立可傳回公司名稱、公司聯絡電子郵件、IPO 年份、股票代號、員工數量和職缺數量的查詢。您可以在 LookML 中定義合併查詢元素，如下所示：
- name: merged_results_element
title: Merged Results Tile
merged_queries:
- model: market_research
explore: company_info
fields: [companies.name, companies.contact_email, ipo.public_year, ipo.stock_symbol]
filters:
companies.contact_email: "-NULL"
ipo.valuation_amount: NOT NULL
sorts: [ipo.public_year desc]
- model: company_data
explore: companies
fields: [companies.name, ipo.stock_symbol, companies.contact_email,
companies.number_of_employees, jobs.job_count]
filters:
companies.number_of_employees: NOT NULL
ipo.stock_symbol: "-NULL"
companies.contact_email: "-NULL"
sorts: [jobs.job_count desc]
join_fields:
- field_name: ipo.stock_symbol
source_field_name: ipo.stock_symbol
- field_name: companies.name
source_field_name: companies.name
- field_name: companies.contact_email
source_field_name: companies.contact_email
將篩選器套用至合併查詢元素
先前的合併查詢元素範例示範了如何使用 filters 參數，直接在每個來源查詢中套用硬式編碼篩選器。舉例來說，主要查詢中的篩選器 companies.contact_email: "-NULL" 和 ipo.valuation_amount: NOT NULL 會將結果限制為具有有效聯絡電子郵件和估值的公司。這些查詢層級篩選器會在合併查詢前預先篩選資料，使用者無法變更。
您也可以在每個來源查詢的定義中使用 listen 參數，將資訊主頁篩選器套用至合併查詢元素。舉例來說，假設您在資訊主頁層級，使用 LookML 資訊主頁的 filters 參數定義了名為 Industry 的資訊主頁篩選器：
filters:
- name: Industry
title: Industry
type: field_filter
ui_config:
type: dropdown_menu
display: inline
model: market_research
explore: company_info
field: companies.industry
如要將 Industry 篩選器套用至兩個來源查詢中的 companies.industry 欄位，請在每個合併查詢的來源查詢定義中加入 listen 參數，如下所示：
listen:
Industry: companies.industry
舉例來說，下列程式碼範例會將 Industry 篩選器，新增至上一個範例中合併結果元素的兩個來源查詢。
- name: merged_results_element
title: Merged Results Tile
merged_queries:
- model: market_research
explore: company_info
fields: [companies.name, companies.contact_email, ipo.public_year, ipo.stock_symbol]
filters:
companies.contact_email: "-NULL"
ipo.valuation_amount: NOT NULL
sorts: [ipo.public_year desc]
listen:
Industry: companies.industry
- model: company_data
explore: companies
fields: [companies.name, ipo.stock_symbol, companies.contact_email,
companies.number_of_employees, jobs.job_count]
filters:
companies.number_of_employees: NOT NULL
ipo.stock_symbol: "-NULL"
companies.contact_email: "-NULL"
sorts: [jobs.job_count desc]
join_fields:
- field_name: ipo.stock_symbol
source_field_name: ipo.stock_symbol
- field_name: companies.name
source_field_name: companies.name
- field_name: companies.contact_email
source_field_name: companies.contact_email
listen:
Industry: companies.industry
新增這項設定後，當使用者與「Industry」資訊主頁篩選器互動時，合併查詢元素中對應的來源查詢也會一併篩選。
hidden_fields
hidden_fields 參數會指出查詢中使用的欄位 (如有)，但這些欄位不會顯示在圖表中。任何隱藏欄位都會顯示在「探索」的資料表部分。
hidden_fields: [inventory_items.count, distribution_centers.id]
樣式參數
本節說明 KPI (單一值) 和單一值 (舊版) 圖表，在圖表編輯器的「樣式」部分中，選項對應的參數。
colors
colors 參數會指定數列的顏色清單。清單中的第一個顏色對應第一個資料序列。如果系列數量超過列出的顏色數量，系統會從頭開始重複使用顏色。
colors: [blue, orange, yellow, red, purple]
對於所有指定顏色的圖表屬性，顏色值可以採用十六進位字串 (例如 #2ca6cd) 或 CSS 具名顏色字串 (例如 mediumblue)。
custom_color_enabled
將 custom_color_enabled 參數設為 true，即可為單一值圖表指定自訂顏色。請搭配使用這項參數和 custom_color 參數。
custom_color_enabled: true | false
custom_color
為單一值圖表中的文字指定自訂顏色。
custom_color: #2ca6cd | mediumblue
show_single_value_title
如果將這個參數設為 true，查詢值下方會顯示標題。您可以使用 single_value_title 參數指定或變更標題。
show_single_value_title: true | false
single_value_title
指定要與查詢值一併顯示的標題。標題文字可以本地化。
single_value_title: Title
valueFormat
指定值的數字或日期格式。這項參數接受 Excel 樣式格式設定。如未指定格式，系統會以基礎維度或測量指標的格式顯示值。
比較參數
本節說明 KPI (單一值) 和單一值 (舊版) 圖表圖表編輯器中，與「Comparison」(比較) 專區選項對應的參數。
show_comparison
如果設為 true，show_comparison 參數可讓您在 type: single_value 的資訊主頁元素中加入比較資訊。
show_comparison: true | false
comparison_type
使用 comparison_type 參數，指定比較欄位在 type: single_value 資訊主頁元素中的使用方式。
您可以為 comparison_type 參數指定下列其中一個值：
value：比較欄位的值會顯示在圖表底部。change：比較欄位的值會顯示在圖表底部。如果值為負數，三角形會向下。如果值為正數，三角形會朝上。progress：將單一值圖表所用欄位的值，除以比較欄位的值。這個百分比會以進度列顯示。progress_percentage：將單一值圖表所用欄位的值，除以比較欄位的值。這個百分比會以進度列顯示。長條會標示比較欄位的百分比和值。
comparison_type: value | change | progress | progress_percentage
show_comparison_label
指定是否要顯示比較欄位的標籤。根據預設，標籤會是比較欄位的名稱。
show_comparison_label: true | false
comparison_label
指定要與比較欄位一併顯示的標籤。比較標籤文字可以本地化。
show_comparison_label: true
comparison_label: Label
comparison_reverse_colors
如果 comparison_type 設為 change，您可以將 comparison_reverse_colors 設為 true，在比較欄位中以綠色文字和綠色三角形顯示負數，並以紅色文字和紅色三角形顯示正數。
comparison_type: change
comparison_reverse_colors: true | false