使用 SQL 设置数据指标函数¶

本主题介绍如何使用 SQL 将数据指标函数 (DMF) 与表或视图关联，以便其定期运行。它还介绍了如何直接调用 DMF，例如，如果要在将 DMF 与表或视图关联之前对其进行测试。

备注

要使用用户界面设置数据质量检查（包括将 DMF 与表关联），请参阅使用 Snowsight 设置数据质量检查。

关联 DMF¶

您可以将 DMF 与表或视图关联，以便定期自动调用它。关联 DMF 时，您指定将哪些列作为实参传递给 DMF。

使用 ALTER TABLE 或 ALTER VIEW 命令关联 DMF 并指定哪些列作为实参传递。例如，以下命令将 NULL_COUNT 系统 DMF 与表 t 关联。DMF 运行时，它将返回列 c1 中的 NULL 值的数量。

ALTER TABLE t
  ADD DATA METRIC FUNCTION SNOWFLAKE.CORE.NULL_COUNT
    ON (c1);

Copy

有些 DMFs 不接受列作为参数。例如，要将 ROW_COUNT 系统 DMF 与视图 v2 关联，请运行以下命令：

ALTER VIEW v2
  ADD DATA METRIC FUNCTION SNOWFLAKE.CORE.ROW_COUNT
    ON ();

Copy

ACCEPTED_VALUES DMF 包含一个 lambda 表达式以及列名，这使您能够检查有多少记录不符合预期值。例如，以下语句将该函数与表 t1 关联，使函数返回 age 列值不等于五的记录数。

ALTER TABLE t1
  ADD DATA METRIC FUNCTION SNOWFLAKE.CORE.ACCEPTED_VALUES ON (age, age -> age = 5);

Copy

从对象中删除 DMF¶

您可以使用 ALTER TABLE 或 ALTER VIEW 命令删除 DMF。例如：

ALTER TABLE t
  DROP DATA METRIC FUNCTION governance.dmfs.count_positive_numbers
    ON (c1, c2, c3);

Copy

调整 DMFs 的计划¶

表、视图或物化视图的 DATA_METRIC_SCHEDULE 对象参数控制 DMFs 频率运行。默认情况下，计划设置为一小时。表或视图上的所有数据指标函数都遵循相同的计划。

您可以使用以下方法来安排 DMF 运行时间：

将 DMF 设置为在指定的分钟数后运行。
使用 cron 表达式计划 DMF，使其按特定的频率运行。
使用触发事件计划 DMF 在表发生 :doc:`DML 更改 </sql-reference/sql-dml>`（例如，在表中插入新行）时运行。但是：
- 表的重聚类不会触发 DMF 运行。
- 触发方法只适用于某些类型的表。有关更多信息，请参阅 :ref:`ALTER TABLE ...<label-alter_table_data_metric_function_action> ` 。

例如：

将数据指标函数计划设置为每 5 分钟运行一次：

ALTER TABLE hr.tables.empl_info SET
  DATA_METRIC_SCHEDULE = '5 MINUTE';

Copy

将数据指标函数计划设置为每天 8:00 AM 运行：

ALTER TABLE hr.tables.empl_info SET
  DATA_METRIC_SCHEDULE = 'USING CRON 0 8 * * * UTC';

Copy

将数据指标函数计划设置为仅在工作日的 8:00 AM 运行：

ALTER TABLE hr.tables.empl_info SET
  DATA_METRIC_SCHEDULE = 'USING CRON 0 8 * * MON,TUE,WED,THU,FRI UTC';

Copy

将数据指标函数计划设置为每天在 0600、1200 和 1800 UTC 时间运行三次：

ALTER TABLE hr.tables.empl_info SET
  DATA_METRIC_SCHEDULE = 'USING CRON 0 6,12,18 * * * UTC';

Copy

将数据指标函数设置为在常规 DML 操作（例如插入新行）修改表时运行：

ALTER TABLE hr.tables.empl_info SET
  DATA_METRIC_SCHEDULE = 'TRIGGER_ON_CHANGES';

Copy

您可以使用 SHOW PARAMETERS 命令查看支持的表对象的 DMF 计划：

SHOW PARAMETERS LIKE 'DATA_METRIC_SCHEDULE' IN TABLE hr.tables.empl_info;

Copy

+----------------------+--------------------------------+---------+-------+------------------------------------------------------------------------------------------------------------------------------+--------+
| key                  | value                          | default | level | description                                                                                                                  | type   |
+----------------------+--------------------------------+---------+-------+------------------------------------------------------------------------------------------------------------------------------+--------+
| DATA_METRIC_SCHEDULE | USING CRON 0 6,12,18 * * * UTC |         | TABLE | Specify the schedule that data metric functions associated to the table must be executed in order to be used for evaluation. | STRING |
+----------------------+--------------------------------+---------+-------+------------------------------------------------------------------------------------------------------------------------------+--------+

对于视图和物化视图对象，将 TABLE 指定为对象域并按如下方式检查计划：

SHOW PARAMETERS LIKE 'DATA_METRIC_SCHEDULE' IN TABLE mydb.public.my_view;

Copy

备注

从修改表的 DMF 开始，会有 10 分钟的滞后，以便任何计划变更对分配给表的先前 DMFs 生效。但是，新分配到表的 DMF 不受 10 分钟延迟的限制。请仔细规划 DMF 计划和 DMF 取消设置操作，以符合您的预期 DMF 成本。

此外，当您评估 DMF 结果（如查询 DATA_QUALITY_MONITORING_RESULTS 视图）时，请在查询中指定 measurement_time 列作为评估的基础。DMF 评估由一个内部流程启动，在计划时间和测量时间之间可能会出现表更新（如 INSERT 操作）。使用 measurement_time 列时，可以更准确地评估 DMF 结果，因为测量时间可以指示 DMF 的评估时间。

暂停 DMFs¶

您可以暂停 DMF 以防止它运行，即使与表关联也可以暂停。或者，您可以使用一个语句，暂停与表关联的所有 DMFs。

**要暂停与表关联的特定 DMF **，请修改关联以设置 SUSPEND 参数。例如：
```
ALTER TABLE t1
  MODIFY DATA METRIC FUNCTION SNOWFLAKE.CORE.NULL_COUNT ON ( col1 )
    SUSPEND;
```
Copy
要恢复运行 DMF，请使用另一个 MODIFY DATA METRIC FUNCTION 语句来设置 RESUME 参数。
**要暂停与表关联的所有 DMFs **，请将表的计划设置为空字符串。例如：
```
ALTER TABLE t1 SET DATA_METRIC_SCHEDULE = '';
```
Copy
要恢复 DMFs，请将 DATA_METRIC_SCHEDULE 参数设置为有效值。

手动调用 DMF¶

直接调用 DMF 有助于测试 DMF 的输出，然后将其与表或视图关联。

使用以下语法调用 DMF:

SELECT <data_metric_function>(<query>)

Copy

其中：

data_metric_function

指定系统定义或用户定义的 DMF。

query

指定对表或视图进行 SQL 查询。

查询投射的列必须与 DMF 签名中的列实参匹配。

备注

以下系统 DMFs 不遵循此语法，因为它们不采用任何实参：

例如，要调用一个自定义 DMF ``count_positive_numbers``（该函数接受三列作为实参），请运行以下命令：

SELECT governance.dmfs.count_positive_numbers(
  SELECT c1, c2, c3
  FROM t);

Copy

例如，要调用 NULL_COUNT（系统数据指标函数）系统 DMF 来查看 ssn 列中的 NULL 值数量，请运行以下命令：

SELECT SNOWFLAKE.CORE.NULL_COUNT(
  SELECT ssn
  FROM hr.tables.empl_info);

Copy

如果自定义 DMF 接受来自多个表的参数，那么每个投影列的查询都必须用括号括起来。例如，如果您想手动调用 REFERENTIAL_CHECK DMF，请执行以下命令：

SELECT referential_check( (SELECT id FROM salesorders), (SELECT id FROM salespeople) );

Copy