使用仪表板参数

本文介绍如何在 AI/BI 仪表板上使用参数。 若要改为了解字段筛选器，请参阅筛选字段。

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

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

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

向查询添加参数

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

若要向查询添加参数：

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

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

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

编辑查询参数

若要编辑参数：

1. 单击参数名称旁边的 。 此时会显示“参数详细信息”对话框，其中包括以下配置选项：

   • 关键字：表示查询中的参数的关键字。 只能通过直接更新查询中的文本来更改它。

   • 显示名称：筛选器编辑器中的名称。 默认情况下，标题与关键字相同。

   • 类型：支持的类型包括字符串、日期、日期和时间、数值。

     • 默认类型为字符串。
     • 数值数据类型允许你在十进制和整数之间进行指定。 默认数值类型为十进制。

   • 允许多个选择：选中复选框以允许用户在运行时选择多个参数。

     注意

     此选择可能需要对查询进行其他更改。 请参阅 “允许多个选择”。

2. 单击 UI 的另一部分以关闭对话框。

设置默认参数值

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

允许多个选择

允许多个选择的查询必须在查询中包含一个 ARRAY_CONTAINS 函数。

下面的示例演示了一个 SQL 查询，该查询允许在运行时选择要插入到查询中的多个值。 子 WHERE 句使用 ARRAY_CONTAINS 函数。 该函数采用参数关键字和列名作为参数。 查询运行时，它将返回包含所选参数值的所有行。

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

若要设置默认值，请在显示名称下的文本字段中键入它们。 在输入下一个值之前选择当前值。

应用日期范围参数

可以使用参数定义范围并仅返回该区域内的结果。 选择以下参数类型之一时，将创建由后缀和.max后缀指定的.min两个参数：

• 日期范围
• 日期和时间范围

以下示例演示一个 SQL 查询，该查询创建名为 <a0/> 的日期范围参数。

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

创建日期范围参数：

1. 单击“ 添加参数”。

2. 单击参数名称旁边的 。 输入关键字和显示名称。 请勿包含 .min 或 .max 后缀。

3. 选择 “日期范围 ”或 “日期和时间范围 ” 作为“类型”。

4. 将定义 WHERE 范围的子句插入到查询中。 若要定义范围，请使用BETWEEN子句和.min.max值。 例如：

    WHERE date_col BETWEEN :date_param.min AND :date_param.max
   

5. 输入默认日期值并运行查询以对其进行测试。 使用日历图标选择预设选项，例如上周或上个月。

基于查询的参数

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

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

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

6. 查看你的仪表板。

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

   

使用筛选条件比较数据

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

以下示例扩展了上一个查询，以包括一个筛选器条件，其中的指定参数值为 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. 单击你希望查看者用于此小组件的参数名称。

使用筛选器小组件和静态参数

参数是运行时替换到查询中的固定值。 如果在仪表板更新时对同一参数的两个或多个引用设置了不同的值，则可视化小组件将显示一个错误，指示哪个参数具有冲突的值。 当多个筛选器小组件使用相同的参数时或当静态参数与允许查看器选择的筛选器小组件冲突时，可能会发生这种情况。

可以使用类似于以下示例中的模式来设置同一查询中不同参数的回退值。

CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

在此示例中，:static_param 指的是静态参数，在可视化小组件和数据集编辑器中都应将其设置为“全部”。 参数 :dash_param 是由仪表板画布上的筛选器小组件控制的动态值。 此语句检查作为静态参数提供的值。 如果未设置任何值，则将回退到查看器选择的仪表板参数值。

在 URL 中包含参数

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

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

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

语法示例

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

重要

如果使仪表板查看者能够通过参数选择（如表或目录名称）访问数据，可能会导致敏感信息意外泄露。 如果要使用这些选项发布仪表板，Azure Databricks 建议不要在已发布的仪表板中嵌入凭据。