本页演示如何使用 dashboard.lkml 文件中的 LookML 信息中心参数添加和自定义 type: looker_pie 的 LookML 信息中心元素。
如需了解如何通过 Looker 界面构建饼图，请参阅饼图选项文档页面。
用法示例
## BASIC PARAMETERS
name: element_name
title: 'Element Title'
type: looker_pie
height: N
width: N
top: N
left: N
row: N
col: N
refresh: N (seconds | minutes | hours | days)
note:
text: 'note text'
state: collapsed | expanded
display: above | below | hover
## QUERY PARAMETERS
model: model_name
explore: explore_name
dimensions: view_name.field_name
measures: view_name.field_name
sorts: [view_name.field_name asc | desc, view_name.field_name, …]
limit: N
column_limit: N
filters:
view_name.field_name: 'Looker filter expression' | 'filter value'
listen:
dashboard_filter_name: dimension_or_measure_name
query_timezone: 'specific timezone' | user_timezone
merged_queries:
- 'primary query definition'
- 'next source query definition'
join_fields:
- field_name: view_name.field_name
source_field_name: view_name.field_name
## PLOT PARAMETERS
value_labels: none | legend | labels
label_type: lab | val | labVal | per | labPer
inner_radius: N
hidden_fields: [view_name.field_name, view_name.field_name, …]
## SERIES PARAMETERS
colors: [css_color, css_color, …]
series_colors:
series_name: css_color
# Possibly more series color assignments
series_labels:
'Series Name': desired series label
# Possibly more series label assignments
参数定义
| 参数名称 | 说明 | |
|---|---|---|
| 基本参数 | ||
name（适用于元素） |
创建元素 | |
title（适用于元素） |
更改元素名称向用户显示的方式 | |
type（适用于元素） |
确定要在元素中使用的可视化类型 | |
height（适用于元素） |
为 layout: tile 和 layout: static 信息中心定义了元素的高度（以 tile_size 为单位） |
|
width（适用于元素） |
以 layout: tile 和 layout: static 信息中心的形式以 tile_size 为单位定义元素的宽度 |
|
top |
以 layout: static 信息中心的 tile_size 为单位定义元素的自上至下位置。 |
|
left |
以 layout: static 信息中心的 tile_size 为单位定义元素的从左到右的位置 |
|
row |
以 layout: newspaper 信息中心行为单位定义元素从上到下的位置 |
|
col |
以 layout: newspaper 信息中心的列为单位定义元素的从左到右的位置 |
|
refresh（适用于元素） |
设置元素自动刷新的时间间隔 | |
note |
启动 LookML 部分以定义元素的备注。此参数包含子参数 text、state 和 display。 |
|
| 查询参数 | ||
model |
定义要用于元素查询的模型 | |
explore（适用于元素） |
定义要用于元素查询的探索 | |
dimensions |
定义要用于元素查询的维度 | |
measures |
定义要用于元素查询的措施 | |
sorts |
定义要用于元素查询的排序 | |
limit |
定义要用于元素查询的行数上限 | |
filters（适用于元素） |
定义针对元素的查询不能更改的过滤条件 | |
listen |
定义当元素创建 filters（针对信息中心）时，可以针对元素查询更改的过滤条件 |
|
query_timezone |
定义运行查询时应使用的时区 | |
merged_queries |
定义合并结果查询 | |
| 图表参数 | ||
value_labels |
更改饼图中各个部分的标记方式 | |
label_type |
自定义用以标记饼图不同部分的标签格式 | |
inner_radius |
确定饼图的内半径，从而有效地将其转换为圆环图 | |
hidden_fields |
指定要在查询中使用但在图表中隐藏的任何字段 | |
| 系列参数 | ||
colors |
根据图表系列的显示顺序设置图表系列的颜色 | |
series_colors |
根据系列名称设置图表系列的颜色 | |
series_labels |
更改系列名称向用户显示的方式 | |
基本参数
定义 LookML 信息中心元素时，您必须至少为 name 和 type 基本参数指定值。其他基本参数（如 title、height 和 width）会影响元素在信息中心的外观和位置。
name
本部分引用了信息中心元素中的
name参数。
name也可以用作信息中心过滤条件的一部分，如信息中心参数文档页面中所述。
每个 name 声明都会创建一个新的信息中心元素并为其命名。元素名称必须是唯一的。使用 layout: grid 信息中心时，elements 参数有时会引用名称。
- 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
如需简要了解不同类型的 LookML 信息中心元素，请参阅 type（适用于 LookML 信息中心）文档页面。
height
本部分引用了信息中心元素中的
height参数。
height也可以用作信息中心行的一部分，如信息中心参数文档页面中所述。
对于具有 tile 或 static 布局的信息中心
height 参数用于为 layout: tile 和 layout: static 信息中心定义元素的高度，以 tile_size（以像素为单位定义）为单位。
例如，以下代码会指定 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 信息中心的元素高度（以 row 为单位）。
报纸版式的信息中心的默认元素高度为 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 形参定义了 layout: tile 和 layout: static 信息中心元素的宽度（以 tile_size 为单位）。
例如，以下代码会指定 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 参数用于定义 layout: static 信息中心元素的元素自上而下的位置（以 tile_size 为单位）。
例如，以下代码会指定 tile_size: 100 和 top: 4，将 orders_by_date 元素的顶部边缘设为位于信息中心顶部 400 像素处。
- dashboard: sales_overview
tile_size: 100
...
elements:
- name: orders_by_date
top: 4
...
left
left 参数用于为 layout: static 信息中心定义元素的从左到右位置（以 tile_size 为单位）。
例如，以下代码会指定 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 参数用于定义元素顶部边缘所在的行。
信息中心从信息中心顶部的第 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 参数定义了元素左侧边缘所在的列。
信息中心分为 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 信息中心元素时，您必须至少使用 dimensions 和 measures 参数指定 model 和 explore 查询参数的值，以及一个维度和一个测量值。您还可以使用下述其他查询参数来控制信息中心元素中数据的显示方式。
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 指定维度或测量值。如果您想使用 Looker 的默认排序顺序，请勿添加 sorts。降序排序以 desc 为后缀；升序排序无需添加后缀。
## single sort example
- name: orders_by_date
sorts: order.order_date desc
## multiple sort example
- name: orders_by_date
sorts: [order.order_date desc, customer.name]
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 液体变量来设置灵活的过滤条件值。
listen
信息中心可以使用过滤条件来更改信息中心元素背后的数据。这些设置通过使用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
例如，您可以创建一个名为 Date 的过滤条件，要求用户在界面中的过滤条件字段中输入日期。然后，您可以将用户输入的值应用到 orders_by_date 元素，如下所示：
- dashboard: sales_overview
...
filters:
- name: date
type: date_filter
elements:
- name: orders_by_date
listen:
date: order.order_date
...
构建 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 子参数来定义合并规则。
merged_queries 的语法为：
merged_queries:
- 'primary query definition'
- 'next source query definition'
join_fields:
- field_name: 'field from the source query using the view_name.field_name syntax'
source_field_name: 'joined field from the primary query using the
view_name.field_name syntax'
# more join_fields definitions as needed
- 'next source query definition'
join_fields:
- field_name: view_name.field_name
source_field_name: view_name.field_name
# more join_fields definitions as needed
# additional source queries and join_fields definitions as needed
在 merged_results 下定义的第一个查询是主查询，其他查询将合并到该查询中。
例如，通过联接股票代码、公司名称和 Twitter 用户名，您可以合并两个查询，以返回公司名称、公司 Twitter 用户名、IPO 年份、股票代码、员工数量和职位数的结果：
- name: merged_results_element
title: Merged Results Tile
merged_queries:
- model: market_research
explore: company_info
fields: [company.name, company.twitter_username, ipo.public_year, ipo.stock_symbol]
filters:
company.twitter_username: "-NULL"
ipo.valuation_amount: NOT NULL
sorts: [ipo.public_year desc]
- model: crunchbase
explore: companies
fields: [companies.name, ipo.stock_symbol, companies.twitter_username,
companies.number_of_employees, jobs.job_count]
filters:
companies.number_of_employees: NOT NULL
ipo.stock_symbol: "-NULL"
companies.twitter_username: "-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: company.name
- field_name: companies.twitter_username
source_field_name: company.twitter_username
数据结果的格式如下所示：
然后，您可以应用元素参数，根据需要设置可视化图表的样式。
绘制参数
本节中介绍的大多数参数都对应于饼图可视化编辑器的图表部分中的选项。
value_labels
通过 type: looker_pie 的信息中心元素的 value_labels 参数，您可以为最终用户更改饼图各部分的标签方式。有三种单独的标签类型：
none：不显示标签和图例。legend：默认选项。图例显示在可视化图表的底部。labels：显示用于标记饼图各个部分的折线。您可以使用label_type参数指定标签类型，从而自定义在这些行旁边显示的信息。
label_type
借助 label_type 参数，您可以自定义标记饼图各个版块的标签格式。如需使用 label_type，必须将 value_type 设置为 labels。您可以通过多种方式来自定义标签：
lab：显示系列名称。val：显示与饼图切片关联的数值。labVal：先以粗体显示系列名称，然后显示数值。per：显示饼图切片在饼图总量中所占的百分比。labPer：先以粗体显示系列名称，然后显示百分比。
inner_radius
此参数用于确定饼图的内半径，从而有效地将饼图转换为圆环图。您提供的百分比表示将由圆环图的“孔”占据的半径部分。
inner_radius: 50
## default value: 0
hidden_fields
hidden_fields 参数用于指明在查询中使用哪些字段（如有），但隐藏在图表中。所有隐藏字段都会显示在“探索”的数据表格部分。
hidden_fields: [inventory_items.count, distribution_centers.id]
系列参数
本部分中介绍的参数对应于饼图可视化编辑器的系列部分中的选项。
colors
colors 参数用于指定系列的颜色列表。列表中的第一个颜色对应第一个数据系列。如果系列颜色多于列出的颜色，颜色会重新开始。
colors: [blue, orange, yellow, red, purple]
对于所有指定颜色的图表属性，颜色值都可以采用十六进制字符串（例如 #2ca6cd）或 CSS 命名的颜色字符串（例如 mediumblue）。
series_colors
使用 name: value 对，根据系列名称设置系列的颜色。
对于透视图表，系列名称是数据透视表名称。
series_colors:
'Yes': skyblue
'No': '#000000'
对于包含多个测量值的图表，系列名称是测量字段名称。
series_colors:
inventory_items.count: crimson
orders.count: green
如果系列名称未在 series_colors 中列出，则该图表将默认使用 colors 中提供的颜色列表。如果未设置 colors，则图表会回退到默认的配色方案。
series_labels
使用 name: label 对，根据系列名称设置一个或多个系列的标签。
对于透视图表，系列名称是数据透视表名称。
series_labels:
'Yes': iOS Users
'No': Android Users
对于包含多个测量值的图表，系列名称是测量字段名称。
series_labels:
inventory_items.count: Inventory
orders.count: Orders