使用仪表板参数

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

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

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

在字段筛选器和参数之间进行选择

参数直接修改查询，这一点可以非常强大。数据集字段筛选器还可以提供仪表板交互性和其他功能，此外与参数相比在处理大型数据集时的性能更好。有关详细信息，请参阅 “我是否应该筛选字段或参数？”。

向查询添加参数

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

Gif 显示了以下步骤的示例。

若要向查询添加参数：

将光标置于查询中要放置参数的位置。
单击“添加参数”以插入新参数。

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

编辑查询参数

若要编辑参数：

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

设置默认参数值

若要测试查询，请在参数名称下的文本字段中键入默认值并运行查询。这会应用参数值，以便预览结果并确认查询按预期运行。运行查询还会保存默认值。

在筛选器小组件中使用参数时，将使用 “数据 ”选项卡中的默认值，除非小组件指定了其他默认值。请参阅使用筛选器。

仪表板设计者应确认在数据集选项卡上，使用所选默认值的参数化查询能够成功运行。Azure Databricks 查询数据集架构，以填充部件配置编辑器。在某些情况下，尤其是使用 IDENTIFIER 子句的参数化查询时，数据集查询可能无法使用默认参数值运行，即使当用户在运行时选择值时会成功。

允许多重选择

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

下面的示例演示了一个 SQL 查询，该查询允许你在运行时选择要插入到查询中的多个值。 WHERE 子句使用 ARRAY_CONTAINS 函数。该函数采用参数关键字和列名作为实参。必须将参数设置为保存多个值，以便可以将它作为数组插入到查询中。当查询运行时，将评估每一行，并且结果集中包含所有l_quantity值匹配:parameter中的任何一个值的行。

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

设置默认值：

编写数据集查询，该查询使用 ARRAY_CONTAINS 函数根据值列表筛选行。
单击参数名称旁边的齿轮图标。请选择“允许多重选择”。

注意

此步骤允许将参数作为数组插入查询中。如果使用 ARRAY_CONTAINS 函数而不启用多个选择，则会发生错误。
在显示名称下的文本字段中键入值。可以输入多个值。在输入下一个值之前选择当前值。

默认值在编辑器中设置。选择多个值并用空格分隔。

应用日期范围参数

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

日期范围
日期和时间范围

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

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

创建日期范围参数：

单击“添加参数”。
单击参数名称旁边的。输入关键字和显示名称。不要包含 .min 或 .max 后缀。
选择“日期范围”或“日期和时间范围”作为“类型”。
将定义范围的 WHERE 子句插入到查询中。若要定义范围，请使用 BETWEEN 子句以及 .min 和 .max 值。例如：
```
 WHERE date_col BETWEEN :date_param.min AND :date_param.max
```
输入默认日期值并运行查询以进行测试。使用日历图标以选择预设选项，例如上周或上个月。

基于查询的参数

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

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

创建一个数据集，其结果集仅限于可能的参数值列表。
创建使用参数的数据集查询。
在画布上配置一个筛选小组件，该小组件会根据字段进行筛选并使用参数。
- “字段”配置应设置为使用具有所需有效参数值列表的字段。
- “参数”配置应设置为选择参数值。

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

注意

如果基于查询的参数中使用的数据集也用于仪表板上的其他可视化效果，则查看者的筛选器选择将修改所有连接的查询。为避免这种情况，创建者应为基于查询的参数创建专用数据集，该数据集不会用于仪表板上的任何其他可视化效果。

创建动态参数列表

若要创建一个动态数据集，用于填充查看者用于选择参数值的下拉列表，请编写一个 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

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

向草稿仪表板画布添加可视化小组件。
选择新的小组件后，从配置面板中的“数据集”下拉列表中选择参数化数据集。
单击“显示筛选器”。对于包含参数的数据集，配置面板中会显示一个新的“参数”部分。
单击“参数”标题右侧的加号，然后从下拉列表中选择参数。
默认情况下，参数值与在“数据”选项卡上的查询中设置的值一摸一样。可以保留该值或选择要替换到数据集中的新值。离开文本字段以显示应用了新参数的可视化效果。
查看你的仪表板。

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

使用筛选条件比较数据

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

以下示例扩展了上一个查询，以包括一个筛选器条件，其中的指定参数值为 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 展示了如何从使用此查询创建的数据集中快速构建三个图表。

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

如上文所述的 gif。

在仪表板上显示参数

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

若要向仪表板添加参数：

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

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

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

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


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

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

在 URL 中包含参数

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

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

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

语法示例

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

重要

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

反馈

此页面是否有帮助？

Last updated on 2025-12-04