使用数据指标函数¶

在尝试本主题中的每个示例之前，请确保您使用的角色符合必要的访问控制要求。

立即衡量：系统 DMF 示例¶

使用以下语法调用 DMF:

SELECT <data_metric_function>(<query>)

Copy

其中：

data_metric_function

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

query

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

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

备注

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

调用系统 DMF 以立即开始衡量数据质量。

例如，调用 NULL_COUNT 系统 DMF 以查看 SSN 列（即，US 社会安全号码）中的 NULL 值数量：

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

Copy

您可以通过查询事件表来查看结果。有关信息，请参阅查看 DMF 结果。

创建自己的 DMF¶

使用 CREATE DATA METRIC FUNCTION 命令创建自己的 DMFs。

创建一个调用 COUNT 函数的 DMF，返回在计算表中前三列时不包含 NULL 值的总行数：

CREATE OR REPLACE DATA METRIC FUNCTION governance.dmfs.count_positive_numbers(
  arg_t TABLE(
    arg_c1 NUMBER,
    arg_c2 NUMBER,
    arg_c3 NUMBER
  )
)
RETURNS NUMBER
AS
$$
  SELECT
    COUNT(*)
  FROM arg_t
  WHERE
    arg_c1>0
    AND arg_c2>0
    AND arg_c3>0
$$;

Copy

有关引用除分配 DMF 的表之外的表的示例，请参阅示例：外键引用。

备注

如果您需要查看 DMF 定义，请使用 DESCRIBE FUNCTION (DMF) 命令。

查看 DMF 的属性¶

描述 DMF 以查看其属性：

DESC FUNCTION governance.dmfs.count_positive_numbers(
  TABLE(
    NUMBER, NUMBER, NUMBER
  )
);

Copy

+-----------+---------------------------------------------------------------------+
| property  | value                                                               |
+-----------+---------------------------------------------------------------------+
| signature | (ARG_T TABLE(ARG_C1 NUMBER, ARG_C2 NUMBER, ARG_C3 NUMBER))          |
| returns   | NUMBER(38,0)                                                        |
| language  | SQL                                                                 |
| body      | SELECT COUNT(*) FROM arg_t WHERE arg_c1>0 AND arg_c2>0 AND arg_c3>0 |
+-----------+---------------------------------------------------------------------+

确保 DMF 的安全¶

将 DMF 设置为安全的 DMF：

ALTER FUNCTION governance.dmfs.count_positive_numbers(
arg_t TABLE(
  arg_c1 NUMBER,
  arg_c2 NUMBER,
  arg_c3 NUMBER
))
SET SECURE;

Copy

列出 DMFs¶

使用 SHOW DATA METRIC FUNCTIONS 或 SHOW FUNCTIONS 命令列出账户、数据库或架构中的 DMFs：

SHOW DATA METRIC FUNCTIONS IN ACCOUNT;

Copy

或者，还可以分别查询 Information Schema FUNCTIONS 视图或 Account Usage FUNCTIONS 视图，以列出指定数据库或账户中的 DMFs。

is_data_metric 列指定函数是否为 DMF。

在 DMF 上设置标签¶

使用 ALTER FUNCTION 命令在 DMF 上设置标签：

ALTER FUNCTION governance.dmfs.count_positive_numbers(
  TABLE(NUMBER, NUMBER, NUMBER))
  SET TAG governance.tags.quality = 'counts';

Copy

在表或视图上添加或删除 DMF¶

使用 ALTER TABLE 或 ALTER VIEW 命令执行以下操作：

使用 ALTER TABLE 在表中添加 DMF。

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

Copy

使用 ALTER TABLE 命令从表中删除 DMF。

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

Copy

跟踪 DMF 引用¶

您可以查询 DATA_METRIC_FUNCTION_REFERENCES Account Usage 视图，以查看账户中的 DMF 引用，也可以调用 DATA_METRIC_FUNCTION_REFERENCES Information Schema 表函数，以识别与给定表或视图关联的 DMFs 或者与给定 DMF 关联的表或视图。

例如：

为每个在该表或视图上设置了名为 count_positive_numbers 的 DMF 的对象（表或视图）返回一行：

USE DATABASE governance;
USE SCHEMA INFORMATION_SCHEMA;
SELECT *
  FROM TABLE(
    INFORMATION_SCHEMA.DATA_METRIC_FUNCTION_REFERENCES(
      METRIC_NAME => 'governance.dmfs.count_positive_numbers'
    )
  );

Copy

为分配给名为 hr.tables.empl_info 的表的每个 DMF 返回一行：

USE DATABASE governance;
USE SCHEMA INFORMATION_SCHEMA;
SELECT *
  FROM TABLE(
    INFORMATION_SCHEMA.DATA_METRIC_FUNCTION_REFERENCES(
      REF_ENTITY_NAME => 'hr.tables.empl_info',
      REF_ENTITY_DOMAIN => 'table'
    )
  );

Copy

计划 DMFs 的运行¶

您可以计划 DMFs 的运行，以自动衡量表的数据质量。

Snowflake 使用表所有者角色（即对表具有 OWNERSHIP 权限的角色）调用计划的 DMF。表所有者角色必须具有以下授权：

对用户定义的 DMF 具有 USAGE 权限，以及对用于存储用户定义的 DMF 的数据库和架构具有 USAGE 权限。
DATA_METRIC_USER 数据库角色（如果 DMF 是系统 DMF）。
对账户具有 EXECUTE DATA METRIC FUNCTION 权限。

通过表或视图的 DATA_METRIC_SCHEDULE 对象参数，可以计划 DMFs 何时运行。表或视图上的所有数据指标函数都遵循相同的计划。

可以通过三种方法计划 DMF 的运行：

将 DMF 设置为在指定的分钟数后运行。
使用 cron 表达式计划 DMF，使其按特定的频率运行。
使用触发事件计划 DMF 在表发生 DML 更改不会触发 DMF 运行。

您可以通过 ALTER TABLE 或 ALTER VIEW 命令设置 DATA_METRIC_SCHEDULE 参数。例如：

将数据指标函数计划设置为每 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 分钟的延迟。这意味着，如果下一个 DMF 操作的计划时间间隔为 5 分钟，并且您现在从表中取消设置 DMF，则 DMF 仍会运行 5 分钟。

因此，请仔细规划 DMF 计划和 DMF 取消设置操作，以符合您的预期 DMF 成本。

手动调用 DMF¶

使用以下语法调用 DMF:

SELECT <data_metric_function>(<query>)

Copy

其中：

data_metric_function

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

query

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

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

备注

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

直接调用 DMF 并查看结果：

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

Copy

当您在表或视图上设置 DMF 并计划其运行时，可以查询根据事件表生成的视图以查看结果。有关信息，请参阅查看 DMF 结果。

查看 DMF 结果¶

Snowflake 在专用的事件表中维护并存储调用 DMF 的结果。要查看 DMF 结果，请选择以下选项之一：

选项 1：查询事件表。
选项 2：查询根据事件表生成的扁平化视图。

根据您希望如何管理对 DMF 结果的访问，这些选项要求将以下一个或两个系统应用程序角色授予一个或多个账户角色：

应用程序角色	描述
DATA_QUALITY_MONITORING_ADMIN	启用以下操作：查询原始表和视图（选项 1 和 2）。截断原始表。不支持其他事件表操作。
DATA_QUALITY_MONITORING_VIEWER	查询视图（仅限选项 2）

应用程序角色

描述

DATA_QUALITY_MONITORING_ADMIN

启用以下操作：

查询原始表和视图（选项 1 和 2）。
截断原始表。不支持其他事件表操作。

DATA_QUALITY_MONITORING_VIEWER

查询视图（仅限选项 2）

例如，使用 GRANT APPLICATION ROLE 命令将 DATA_QUALITY_MONITORING_VIEWER 系统应用程序角色授予 analyst 自定义角色：

USE ROLE ACCOUNTADMIN;
GRANT APPLICATION ROLE SNOWFLAKE.DATA_QUALITY_MONITORING_VIEWER TO ROLE analyst;

Copy

使用 REVOKE APPLICATION ROLE 命令撤消账户角色中的系统应用程序角色。

选项 1：查询事件表

通过此选项，可以访问原始数据，并且可以更自由地使用派生对象对数据进行后处理，例如根据分析结果所需的方式创建视图、表函数或存储过程。此外，如果创建这些派生对象，可以有选择地向不同的角色授予对这些对象的访问权限。例如，数据工程师可以访问存储过程以维护获取结果的方法，而数据分析师可以访问视图来分析结果。

事件表命名为 SNOWFLAKE.LOCAL.DATA_QUALITY_MONITORING_RESULTS_RAW。

有关事件表列的信息，请参阅事件表列。

有关查询事件表的代表性示例，请参阅日志记录和跟踪教程。

选项 2：查询根据事件表生成的扁平化视图

通过此选项，可以查询 DATA_QUALITY_MONITORING_RESULTS 视图，该视图会扁平化事件表中的原始数据，以便更轻松地访问 DMF 结果。此外，不需要数据后处理以及不需要授予对原始数据的访问权限时，最好选择此选项。

该视图存在于 SNOWFLAKE 共享数据库的 LOCAL 架构中：SNOWFLAKE.LOCAL.DATA_QUALITY_MONITORING_RESULTS。

有关信息，请参阅 DATA_QUALITY_MONITORING_RESULTS 视图。

备注

SNOWFLAKE.GOVERNANCE_VIEWER 数据库角色无权查询 DATA_QUALITY_MONITORING_RESULTS 视图。

从系统中删除 DMF¶

从系统中删除 DMF：

DROP FUNCTION governance.dmfs.count_positive_numbers(
  TABLE(
    NUMBER, NUMBER, NUMBER
  )
);

Copy

限制¶

有关信息，请参阅数据质量限制部分。