LookML 信息中心的单值图表参数

正在建设中： 我们正在努力为此页面添加更多内容。在此期间，您可以查看单值图表选项文档页面，了解如何使用可视化选项菜单创建和修改单值可视化图表。

本页介绍的参数适用于 type: single_value 的 LookML 信息中心元素，这些元素位于 dashboard.lkml 文件中。

如需了解如何通过 Looker 界面构建单值图表，请参阅 单值图表选项 文档页面。

基本参数

定义 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) Sales Overview ，而不是 Sales Overview 。

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 布局的信息中心

对于 layout: tile 和 layout: static 信息中心，height 参数用于定义元素的高度，单位为 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 布局的信息中心

对于 layout: newspaper 信息中心，height 参数用于定义元素的高度，单位为 行。

采用报纸布局的信息中心默认元素高度为 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 也可以用作信息中心的一部分，如 信息中心参数 文档页面中所述。

对于 layout: tile 和 layout: static 信息中心，width 参数用于定义元素的宽度，单位为 tile_size。

例如，以下代码指定了 tile_size: 100 和 width: 4，使 orders_by_date 元素的宽度为 400 像素。

- dashboard: sales_overview
  tile_size: 100
  ...

  elements:
  - name: orders_by_date
    width: 4
    ...

对于 layout: newspaper 信息中心，width 参数用于定义元素的宽度，单位为列。

采用报纸布局的信息中心默认宽度为 24 列。

例如，以下代码将元素的宽度设置为信息中心宽度的一半：

- dashboard: sales_overview
  layout: newspaper
  ...

  elements:
  - name: orders_by_date
    width: 12
    ...

top

对于 layout: static 信息中心，top 参数用于定义元素从上到下的位置，单位为 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

对于 layout: static 信息中心，left 参数用于定义元素从左到右的位置，单位为 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 信息中心元素时，您必须为至少 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 参数用于定义应为元素查询使用的行数上限。此上限适用于应用任何透视之前的行数。before

- 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 语法引用过滤条件应应用的字段。例如，您可以创建一个名为 Date 的过滤条件，要求用户在界面中的过滤条件字段中输入日期。然后，您可以将用户输入的值应用于 orders_by_date 元素，如下所示：

- dashboard: sales_overview
  ...

  filters:
  - name: date
    type: date_filter

  elements:
 - name: orders_by_date
    listen:
      date: order.order_date
    ...

如需查看使用 filters 参数和 listen 参数将信息中心过滤条件应用于各个信息中心元素的其他示例，请参阅 构建 LookML 信息中心。

query_timezone

query_timezone 参数用于指定运行查询的时区。时区选项显示在 Values for 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 参数，将 信息中心过滤条件 应用于合并查询元素。例如，假设您有一个名为 Industry 的信息中心过滤条件，您已使用 LookML 信息中心的 filters 参数在信息中心级定义了该过滤条件：

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 信息中心过滤条件互动时，合并查询元素中的相应源查询将相应地进行过滤。

提示： 每个源查询都可以监听一个或多个信息中心过滤条件。这样，无论合并结果元素中有多少个源查询，您都可以为每个源查询单独定义过滤条件逻辑。如果查询没有 listen 参数，则不会受到任何信息中心过滤条件的影响。

hidden_fields

hidden_fields 参数用于指示查询中使用了哪些字段（如果有），但这些字段在图表中处于隐藏状态。任何隐藏字段都会显示在探索的数据表部分。

hidden_fields: [inventory_items.count, distribution_centers.id]

样式参数

本部分介绍的参数对应于单值图表的可视化编辑器中样式 部分的选项。

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 样式的格式。如果未指定任何格式，值将以底层维度或衡量指标的格式显示。

比较参数

本部分介绍的参数对应于单值图表的可视化编辑器中比较 部分的选项。

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