什么是仪表板参数？

项目
05/14/2024

仪表板参数是使仪表板具有交互性的一种方法，它使查看者能够使用单值选择器和日期选取器在运行时将特定值输入到数据集查询中。例如，参数可以根据日期和产品类别等条件筛选数据，然后在 SQL 查询中聚合它们，从而实现更高效的查询和精确分析。

参数会添加到数据集中，并由仪表板创建者或编辑者连接到仪表板画布上的一个或多个小组件。仪表板查看者通过在运行时选择筛选器小组件中的值来与仪表板数据进行交互。这会重新运行关联的查询，并显示基于筛选的数据生成的可视化效果。

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

向查询添加参数

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

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

若要向查询添加参数：

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

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

编辑查询参数

若要编辑参数：

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

设置默认参数值

可以在参数名称下的文本字段中通过键入的方式来设置参数的默认值。运行查询以预览应用了参数值的查询结果。运行查询还会保存默认值。在画布上使用筛选器小组件设置此参数时，将使用默认值。

基于查询的参数

基于查询的参数允许创建者定义查看者在浏览仪表板中的数据时可以选择的值的动态或静态列表。若要创建基于查询的参数，仪表板创建者需执行以下步骤：

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

注意

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

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

创建动态参数列表

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

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

创建静态参数列表

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

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

筛选器类型

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

删除查询参数

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

在仪表板上显示参数

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

若要向仪表板添加参数：

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

在 URL 中包含参数

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

参数语法示例

以下示例演示了参数的一些常见用例。

插入日期

以下示例包含一个 Date 参数，用于将查询结果限制为特定日期后的记录。


SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY
  1,
  2

插入数字

以下示例包含一个 Numeric 参数，用于将结果限制为 o_total_price 字段大于提供的参数值的记录。


SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

插入字段名称

在以下示例中，field_param 与 IDENTIFIER 函数搭配使用，在运行时为查询提供阈值。参数值应是查询中使用的表中的列名。


SELECT
  *
FROM
  samples.tpch.orders
WHERE
  IDENTIFIER(:field_param) < 10000

插入数据库对象

以下示例创建了三个参数：catalog、schema 和 table。仪表板查看者可以使用画布上的筛选器小组件来选择参数值。


SELECT
  *
FROM
  IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

请参见 IDENTIFIER 子句。

重要

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

连接多个参数

可以在其他 SQL 函数中包含参数。在此示例中，查看者可以选择员工职称和编号 ID。查询使用 format_string 函数连接两个字符串，并筛选匹配的行。请参阅 format_string 函数。


SELECT
  o_orderkey,
  o_clerk
FROM
  samples.tpch.orders
WHERE
  o_clerk LIKE format_string('%s%s', :title, :emp_number)

使用仪表板参数与Databricks SQL 查询参数

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

Share via