使用仪表板参数

本文介绍如何在 AI/BI 仪表板上使用参数。

AI/BI 仪表板参数使你能够在运行时将不同的值替换到数据集查询中。 这使你能够根据日期和产品类别等条件筛选数据，然后在 SQL 查询中聚合数据，从而实现更高效的查询和精确分析。 参数可与筛选器小组件配合使用，使仪表板具有交互性，参数也可与可视化小组件配合使用，使数据集更易于重用。

仪表板作者或编辑者将参数添加到数据集，并将参数连接到仪表板画布上的一个或多个小组件。 对于在可视化小组件中设置的静态参数，参数值将由作者或编辑者设置。 对于筛选器小组件中使用的参数，仪表板查看者可以通过在运行时选择筛选器小组件中的值来与数据交互。 该交互会重新运行关联的查询，并显示基于筛选的数据的可视化效果。

参数直接修改查询，这一点可以非常强大。 数据集字段筛选器还可以提供仪表板交互性和其他功能，此外与参数相比在处理大型数据集时的性能更好。 请参阅筛选器。

向查询添加参数

必须至少对草稿仪表板拥有“可编辑”权限才能将参数添加到仪表板数据集。 可以直接将参数添加到“数据”选项卡中的数据集查询。

若要向查询添加参数：

1. 将光标置于查询中要放置参数的位置。

2. 单击“添加参数”以插入新参数。

   这会创建具有默认名称 parameter 的新参数。 若要更改默认名称，请在查询编辑器中替换它。 还可以通过在查询编辑器中键入此语法来添加参数。

编辑查询参数

若要编辑参数：

1. 单击参数名称旁边的 。 此时会显示“参数详细信息”对话框，其中包含以下配置选项：
   • 关键字：表示查询中的参数的关键字。 只能通过直接更新查询中的文本来更改它。
   • 显示名称：筛选器编辑器中的名称。 默认情况下，标题与关键字相同。
   • 类型：支持的类型包括字符串、日期、日期和时间、数值。
     • 默认类型为字符串。
     • 数值数据类型允许你在十进制和整数之间进行指定。 默认数值类型为十进制。
2. 单击 UI 的另一部分以关闭对话框。

设置默认参数值

要使查询能够运行，可以通过在参数名称下的文本字段中键入值来设置参数的默认值。 运行查询以预览应用了参数值的查询结果。 运行查询还会保存默认值。 在画布上使用筛选器小组件设置此参数时，除非在筛选器小组件中指定了新的默认值，否则将使用现有默认值。 请参阅筛选器。

基于查询的参数

基于查询的参数允许创建者定义一个动态或静态的值列表，查看者一边浏览仪表板中的数据一边设置参数时可以从中进行选择。 它们是通过在单个筛选器小组件中组合字段筛选器和参数筛选器来定义的。

若要创建基于查询的参数，仪表板创建者需执行以下步骤：

1. 创建一个数据集，其结果集仅限于可能的参数值列表。
2. 创建使用参数的数据集查询。
3. 在画布上配置筛选字段并使用参数的筛选器小组件。
   • “字段”配置应设置为将字段与符合条件的参数值列表一起使用。
   • “参数”配置应设置为选择参数值。

有关演示如何添加基于查询的参数和可视化效果的分步教程，请参阅使用基于查询的参数。

创建动态参数列表

若要创建一个动态数据集，用于填充查看者用于选择参数值的下拉列表，请编写一个 SQL 查询，该查询返回单个字段并包含该字段中的所有值。 更新数据集时，该字段中的任何新值都会自动添加为参数选择。 示例 SQL 查询如下所示：

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

创建静态参数列表

可以创建仅包含硬编码到你的数据集的值的静态数据集。 示例查询如下所示：

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

筛选器类型

“单个值”和“日期选取器”筛选器支持设置参数。 使用“日期选取器”筛选器设置基于查询的参数时，基础查询结果中显示的日期显示为黑色。 查询结果中未显示的日期为灰色。 用户也可以选择灰色日期，即使它们不包含在基础查询中。

删除查询参数

若要移除参数，请将其从查询中删除。

静态小组件参数

静态小组件参数直接在可视化小组件中配置，允许作者单独参数化共享同一数据集的可视化小组件。 这样，同一数据集就可以在画布上展示不同的视图。

本部分中的此示例基于查询 samples.nyctaxi.trips 表的数据集。 提供的查询返回每个行程的距离，并将取件日分类为 Weekday 或 Weekend。 查询参数根据是在工作日还是在周末发生取件来筛选结果。

查询文本在以下代码块中提供，但本节中的说明仅限于设置使用静态小组件参数配置的关联可视化。 有关如何使用参数设置数据集的说明，请参阅向查询添加参数。

  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

将静态小组件参数添加到可视化：

1. 向草稿仪表板画布添加可视化小组件。

2. 选择新的小组件后，从配置面板中的“数据集”下拉列表中选择参数化数据集。 对于包含参数的查询，配置面板中会显示一个新的“参数”部分。

   

3. 单击“参数”标题右侧的加号，然后从下拉列表中选择参数。

4. 默认情况下，参数值与在“数据”选项卡上的查询中设置的值一摸一样。可以保留该值或选择要替换到数据集中的新值。 离开文本字段以显示应用了新参数的可视化效果。

5. 查看你的仪表板。

   下图显示了两个可视化小组件，每个小组件都配置为具有静态小组件参数的直方图。 左侧的图表显示从工作日开始的行程的行程距离分布，而右侧的图表显示周末的相同数据。 这两个可视化都基于同一数据集。

   

使用筛选条件比较数据

可以添加一个筛选器条件，以便将部分数据的聚合与应用于整个数据集的聚合进行比较。

以下示例扩展了上一个查询，以包括一个筛选器条件，其中的指定参数值为 All，它不出现在数据中。 筛选条件的第一部分的工作方式与上一个示例相同，筛选 day_type 为 Weekday 或 Weekend 的结果。 筛选条件的第二部分检查参数本身是否设置为特定值（在本例中为 All），它不会出现在数据中。 在数据集编辑器中为该参数设置默认值时，如果 Weekday 和 Weekend 均未作为值传入，则实际上是绕过了筛选器。

WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

可以使用此数据集来配置三个可视化小组件，day_type_param 分别设置为 All、Weekday 和 Weekend。 然后，仪表板查看者可以将按日期类型筛选的每个数据集与整个数据集进行比较。

以下 GIF 展示了如何从使用此查询创建的数据集中快速构建三个图表。

1. 第一个图表配置为显示“行程距离（按天类型）”数据集，参数值设置为“工作日”。
2. 克隆图表以维护所有已应用的配置。
3. 若要显示周末行程的数据，请将静态参数调整为“周末”。
4. 克隆该新图表以保持之前应用的所有配置。
5. 在新图表中将参数设置为“全部”，以按周末和工作日行程的距离显示总行程计数。

在仪表板上显示参数

通过向仪表板画布添加筛选器，查看者可以选择和修改参数值，以便他们能够以交互方式浏览和分析数据。 如果未在仪表板上公开参数，则查看者只能看到使用查询中设置的默认参数值的查询结果。

若要向仪表板添加参数：

1. 单击 “添加筛选器(字段/参数)”。
2. 在配置面板中单击“参数”旁边的 。
3. 单击你希望查看者用于此小组件的参数名称。

在 URL 中包含参数

参数设置存储在 URL 中，使用户可以为其添加书签以维护仪表板的状态，包括预设置的筛选器和参数，或者与其他人共享，从而一致地应用相同的筛选器和参数。

仪表板参数与 Mustache 查询参数比较

仪表板参数使用与已命名的参数标记相同的语法。 请参阅已命名的参数标记。 仪表板不支持 Mustache 样式参数。

语法示例

参数的常见用途包括通过 JSON 字符串插入日期、数字、文本、数据库对象和值。 有关演示如何在这些情况下使用参数的示例，请参阅命名参数语法示例