将参数与指标视图配合使用

参数允许在查询值时将值传递到指标视图中。 使用参数可跨不同的输入重复使用单个 指标视图 定义，例如折扣率或日期窗口。 可以在任何可使用常量 SQL 表达式的位置引用参数，例如筛选条件、字段和度量值表达式、数据源以及联接。 查询视图时，将值作为参数传递。

参数可减少重复。 无需为每个变体维护单独的指标视图，而是定义一次逻辑，让每个调用方提供自己的值。 参数可以包含默认值，因此不传递参数的调用方会回退到默认值。

可以从 SQL 查询或 AI/BI 仪表板传递参数值。 在仪表板中，将参数与筛选器小组件关联，让查看者在运行时选择参数值。 请参阅 在仪表板中使用参数化查询。

Requirements

  • 若要创建用于定义参数的指标视图，你需要拥有该架构上的CREATE TABLE和USE SCHEMA权限，以及父目录上的USE CATALOG权限。 有关创建指标视图所需的权限的完整列表，请参阅 “创建指标”视图。
  • 若要查询定义参数的指标视图，需要 SQL 仓库或其他运行 Databricks Runtime 18.2 或更高版本的计算资源。 有关更多版本要求，请参阅 指标视图功能可用性。

Limitations

以下限制适用于定义参数的指标视图：

  • 无法具体化定义参数的指标视图。
  • 默认值有限制。 默认值必须可强制转换为参数的声明数据类型，并且不能引用另一个参数或包含子查询。 如果为一个参数设置了默认值，则后面的每个参数也必须具有默认值。 请参阅参数。

定义参数

可以在目录资源管理器低代码编辑器中或直接在 YAML 中定义参数。 创建参数后，在常量 SQL 表达式有效的任意位置（例如筛选器、字段和度量值表达式、源和联接中）按名称引用它。

若要在 YAML 中定义参数，请将顶级 parameters 块添加到指标视图定义。 有关完整的字段引用和 YAML 示例，请参阅 “参数”。

以下步骤将使用目录浏览器低代码编辑器以及每个工作区中都提供的 samples.tpch.orders 表，构建一个包含 discount 参数和两个度量值的指标视图。 一个度量值应用参数，另一个度量值计算未记入的总和，以便比较这两个度量值。

步骤 1：创建指标视图

创建一个指标视图来保存参数和度量值。

  1. 单击“数据”图标。工作区边栏中的目录，然后使用搜索栏查找samples.tpch.orders并单击表名。
  2. 单击创建>指标视图。
  3. 在 “创建指标视图 ”对话框中，输入一个名称，然后选择一个目录和架构以在其中创建指标视图。 单击 “创建” 。

编辑器将在 UI 选项卡上打开。有关指标视图编辑器的完整演练，请参阅 “创建指标”视图。

步骤 2：添加参数

添加具有 discount 数值类型和默认值的参数。

  1. 在编辑器标题中，单击“ 添加参数”。

  2. 在 “参数详细信息 ”对话框中：

    1. 输入discount。
    2. 从“类型”下拉列表中选择“数值”。
    3. 从显示的数值类型下拉列表中选择“Double”。

    “添加参数”按钮和“参数详细信息”对话框，其折扣参数设置为数字类型和双数值类型。

  3. 单击对话框外部以关闭该对话框，然后输入 0.15 作为 折扣 的默认值。

    默认值为 0.15 的折扣参数。

创建参数后，该参数将显示在编辑器标题中。 此处设置的值是查询省略参数时适用的默认值。

步骤 3：添加使用参数的度量值

按名称在度量值表达式中引用参数。 此度量值将折扣应用于每个订单总计。

  1. 单击编辑器顶部附近的“ 度量值 ”选项卡。

  2. 单击 + 添加。

  3. 输入 Discounted Sales 为 度量值名称。

  4. 单击“ 自定义”，然后输入以下表达式：

    SUM((1 - discount) * source.o_totalprice)

步骤 4：添加另一个度量值

为未列出的总计添加第二个度量值。

  1. 单击 + 添加。
  2. 输入 Total Sales 为 度量值名称。
  3. 在 Builder 中，选择 source.o_totalprice 和 Sum 聚合，以生成 SUM(source.o_totalprice)。

步骤 5：保存指标视图

单击“ 保存”。 若要查询指标视图并传递参数的值 discount ，请参阅 使用参数查询指标视图。

使用参数查询指标视图

若要查询定义参数的指标视图，请将指标视图作为表值函数调用，并将参数作为参数传递。 可以按名称或位置传递参数，或省略参数以使用默认值。

按名称传递参数

若要按名称传递参数，请使用 => 运算符。 以下示例将值 discount 传递给 0.15：

SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(discount => 0.15)
GROUP BY product;

按位置传递参数

若要按位置传递参数，请按定义参数的顺序列出值。 以下示例传递了相同的 discount 值 0.15：

SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(0.15)
GROUP BY product;

使用默认参数值

若要在调用指标视图时使用默认参数值，请省略参数。 以下查询是等效的，使用所有默认值：

SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view() GROUP BY product;
SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view GROUP BY product;

查看指标视图定义的参数

若要查看指标视图定义的参数，请查看其 YAML 定义，其中包括 parameters 块。 请参阅 “查看指标视图定义和元数据”。

在仪表板中使用参数化查询

可以使用其中任何一个查询在 AI/BI 仪表板中定义数据集。 引用 SQL 数据集中的指标视图，并将参数作为表值函数调用中的参数传递。 若要让仪表板查看者在运行时选择值，请将仪表板参数传递给该参数，并将其连接到筛选器控件。 请参阅 将参数传递给指标视图。

其他资源

  • Last updated on