Snowflake 类¶

SNOWFLAKE 数据库还包括 Snowflake 提供的类。

概念¶

类与面向对象编程中的类相似，用作创建实例的蓝图。实例是从类中创建的对象。类和实例是 Snowflake 中的架构级对象。您可以将类视为可扩展的 Snowflake 对象类型，将实例视为 Snowflake 对象。

类通过存储过程和函数提供公共 API。它们统称为 类方法。类还提供 类角色，用于对类方法启用细粒度权限。除了其公共 API 之外，类还包括私有状态以及私有过程和函数，类似于面向对象编程中的私有属性和方法。类的实现可以随着时间的推移，通过新的 类版本 不断演变。Snowflake 会自动将实例升级到最新的类版本。

例如，Snowflake 在 SNOWFLAKE.ML 架构中提供了 ANOMALY_DETECTION 类。您可以使用 CREATE 命令创建类的实例，就像创建特定对象类型的对象一样。

下面的示例创建了一个类的实例并调用了一个实例方法。

更新搜索路径，使其包含 SNOWFLAKE.ML：
```
ALTER SESSION SET SEARCH_PATH = '$current, $public, snowflake.ml';
```
创建 ANOMALY_DETECTION 类的实例：
```
CREATE ANOMALY_DETECTION mydatabase.myschema.my_anomaly_detector(...);
```
创建 ANOMALY_DETECTION 类的实例后，可以调用实例方法：
```
mydatabase.myschema.my_anomaly_detector!DETECT_ANOMALIES(...);
```

备注

目前，类仅由 Snowflake 提供，不能由用户创建。

列出可用的类¶

您可以使用 SHOW 命令查找可用的类，并了解有关每个类的更多信息。这些命令使您能够：

查找 SNOWFLAKE 数据库中所有可用的类。
列出类方法。
列出类角色。

查找所有类¶

通过执行 SHOW CLASSES 命令可以列出所有可用的 Snowflake 类：

SHOW CLASSES IN DATABASE SNOWFLAKE;

该语句的结果包括每个类的数据库和架构名称。

更新搜索路径¶

类是 SNOWFLAKE 数据库中的架构中的对象。必须使用完全限定的类名称（例如，SNOWFLAKE.ML.ANOMALY_DETECTION）来执行本主题中的后续 SQL 命令。或者，可以更新搜索路径，使其包含类的数据库和架构，然后通过其非限定名称（例如，ANOMALY_DETECTION）引用该类。

备注

如果更新特定类的搜索路径，则具有相同名称但属于不同类的函数将不再可访问。例如，如果您将 SNOWFLAKE.CORTEX 添加到您的搜索路径，字符串函数 TRANSLATE 将无法访问，因为已存在 SNOWFLAKE.CORTEX.TRANSLATE 函数。

可以使用 ALTER SESSION、ALTER USER 或 ALTER ACCOUNT 修改搜索路径。


命令	备注
ALTER SESSION	仅修改当前会话的搜索路径。您可以在会话级别修改自己的搜索路径。会话级更改会替换账户级或用户级设置。
ALTER USER	持续修改当前或指定用户的搜索路径。您可以在用户级别修改自己的搜索路径。管理员可以修改其他用户的搜索路径。用户级更改会替换账户级或会话级设置。
ALTER ACCOUNT	持续修改账户中所有用户的搜索路径。管理员必须在账户级别修改搜索路径。

执行以下语句，并从 value 列中复制当前搜索路径：
```
SHOW PARAMETERS LIKE 'search_path';
```
更新搜索路径。

备注

以下示例使用默认搜索路径 $current, $public。如果上一步 value 列中的搜索路径与默认值不匹配，请编辑下面的示例语句，使其包含您的实际搜索路径。

例如，要将 SNOWFLAKE.ML 添加到当前会话的搜索路径中，请执行以下语句：
```
ALTER SESSION SET SEARCH_PATH = '$current, $public, SNOWFLAKE.ML';
```
要在用户级别将 SNOWFLAKE.ML 添加到您自己的搜索路径中，请执行以下语句：
```
ALTER USER SET SEARCH_PATH = '$current, $public, SNOWFLAKE.ML';
```
具有 ACCOUNTADMIN 角色的用户可以通过执行以下语句来更新账户的搜索路径：
```
ALTER ACCOUNT SET SEARCH_PATH = '$current, $public, SNOWFLAKE.ML';
```

有关 Snowflake 如何解析名称的更多信息，请参阅对象名称解析。

类方法¶

类通过存储过程和函数提供公共 API。它们统称为类方法。要列出类的所有方法（包括每个方法所需的实参），请执行 SHOW FUNCTIONS IN CLASS 和 SHOW PROCEDURES IN CLASS 命令。一个类可能包含多个名称相同但签名不同的方法（即，不同数量的实参或实实参据类型）。

备注

本主题中的示例语句使用非限定类名称 ANOMALY_DETECTION 。如果尚未更新搜索路径使其包含 SNOWFLAKE.ML，请使用 SNOWFLAKE.ML.ANOMALY_DETECTION 类的完全限定名称。

例如，要列出 SNOWFLAKE.ML.ANOMALY_DETECTION 类中所有可用的函数，请执行以下语句：

SHOW FUNCTIONS IN CLASS ANOMALY_DETECTION;

+-----------------------+-------------------+-------------------+--------------------------------------------------------------------------+--------------+----------+
| name                  | min_num_arguments | max_num_arguments | arguments                                                                | descriptions | language |
|-----------------------+-------------------+-------------------+--------------------------------------------------------------------------+--------------+----------|
| _DETECT_ANOMALIES_1_1 |                 5 |                 5 | (MODEL BINARY, TS TIMESTAMP_NTZ, Y FLOAT, FEATURES ARRAY, CONFIG OBJECT) | NULL         | Python   |
| _FIT                  |                 3 |                 3 | (TS TIMESTAMP_NTZ, Y FLOAT, FEATURES ARRAY)                              | NULL         | Python   |
| _FIT                  |                 4 |                 4 | (TS TIMESTAMP_NTZ, Y FLOAT, LABEL BOOLEAN, FEATURES ARRAY)               | NULL         | Python   |
+-----------------------+-------------------+-------------------+--------------------------------------------------------------------------+--------------+----------+

要列出 SNOWFLAKE.ML.ANOMALY_DETECTION 类中的所有存储过程，请执行以下语句：

SHOW PROCEDURES IN CLASS ANOMALY_DETECTION;

以下结果包括会话中当前角色已被授予访问权限的类中的存储过程：

+---------------------------------+-------------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------+--------------+------------+
| name                            | min_num_arguments | max_num_arguments | arguments                                                                                                                                | descriptions | language   |
|---------------------------------+-------------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------+--------------+------------|
| __CONSTRUCT                     |                 4 |                 4 | (INPUT_DATA VARCHAR, TIMESTAMP_COLNAME VARCHAR, TARGET_COLNAME VARCHAR, LABEL_COLNAME VARCHAR)                                           | NULL         | Javascript |
| __CONSTRUCT                     |                 5 |                 5 | (INPUT_DATA VARCHAR, SERIES_COLNAME VARCHAR, TIMESTAMP_COLNAME VARCHAR, TARGET_COLNAME VARCHAR, LABEL_COLNAME VARCHAR)                   | NULL         | Javascript |
| DETECT_ANOMALIES                |                 4 |                 4 | (INPUT_DATA VARCHAR, SERIES_COLNAME VARCHAR, TIMESTAMP_COLNAME VARCHAR, TARGET_COLNAME VARCHAR)                                          | NULL         | SQL        |
| DETECT_ANOMALIES                |                 5 |                 5 | (INPUT_DATA VARCHAR, SERIES_COLNAME VARCHAR, TIMESTAMP_COLNAME VARCHAR, TARGET_COLNAME VARCHAR, CONFIG_OBJECT OBJECT)                    | NULL         | SQL        |
| DETECT_ANOMALIES                |                 3 |                 3 | (INPUT_DATA VARCHAR, TIMESTAMP_COLNAME VARCHAR, TARGET_COLNAME VARCHAR)                                                                  | NULL         | SQL        |
| DETECT_ANOMALIES                |                 4 |                 4 | (INPUT_DATA VARCHAR, TIMESTAMP_COLNAME VARCHAR, TARGET_COLNAME VARCHAR, CONFIG_OBJECT OBJECT)                                            | NULL         | SQL        |
| EXPLAIN_FEATURE_IMPORTANCE      |                 0 |                 0 | ()                                                                                                                                       | NULL         | SQL        |
| _CONSTRUCTFEATUREINPUT          |                 6 |                 6 | (INPUT_REF VARCHAR, SERIES_COLNAME VARCHAR, TIMESTAMP_COLNAME VARCHAR, TARGET_COLNAME VARCHAR, LABEL_COLNAME VARCHAR, REF_ALIAS VARCHAR) | NULL         | Javascript |
| _CONSTRUCTINFERENCEFUNCTIONNAME |                 0 |                 0 | ()                                                                                                                                       | NULL         | SQL        |
| _CONSTRUCTINFERENCERESULTAPI    |                 0 |                 0 | ()                                                                                                                                       | NULL         | SQL        |
| _SETTRAININGINFO                |                 0 |                 0 | ()                                                                                                                                       | NULL         | SQL        |
+---------------------------------+-------------------+-------------------+------------------------------------------------------------------------------------------------------------------------------------------+--------------+------------+

类角色¶

一个类可能具有一个或多个角色，这些角色被授予对某些类方法或所有类方法的 USAGE 权限。您可以使用 SHOW ROLES IN CLASS 命令列出类中的可用角色。

列出 SNOWFLAKE.ML.ANOMALY_DETECTION 类中的所有角色：

SHOW ROLES IN CLASS ANOMALY_DETECTION;

+-------------------------------+------+---------+
| created_on                    | name | comment |
|-------------------------------+------+---------|
| 2023-06-06 01:06:42.808 +0000 | USER | NULL    |
+-------------------------------+------+---------+

实例角色¶

角色在类中定义，并在实例中实例化为 实例角色。可以向账户中的角色授予实例角色，以启用对实例方法的访问权限。

例如，如果您在架构 my_db.my_schema 中有一个 ANOMALY_DETECTION 实例 my_anomaly_detector，则可以使用以下语句查看授予实例角色 USER 的权限：

SHOW GRANTS TO SNOWFLAKE.ML.ANOMALY_DETECTION ROLE my_db.my_schema.my_anomaly_detector!USER;

要将实例角色授予您账户中的角色 my_role，请执行以下语句：

GRANT SNOWFLAKE.ML.ANOMALY_DETECTION ROLE my_db.my_schema.my_anomaly_detector!USER
  TO ROLE my_role;

上面的语句使角色 my_role 能够执行 ANOMALY_DETECTOR 实例 my_anomaly_detector 的方法。

备注

角色 my_role 还必须对数据库 my_db 和架构 my_schema 具有 USAGE 权限。角色 my_role 还必须对传递给实例方法的对象具有适当权限。

授予创建类实例的权限¶

为了创建类的实例，必须向角色授予 CREATE <class_name> 权限。

例如，要使 ml_admin 角色能够在 mydb.myschema 架构中创建 SNOWFLAKE.ML.ANOMALY_DETECTION 实例，请执行以下语句：

GRANT CREATE ANOMALY_DETECTION ON SCHEMA mydb.myschema TO ROLE ml_admin;

创建实例¶

可以使用 CREATE <object> 命令和类构造函数方法创建类的实例。

备注

无论实例是从哪个类创建的，架构中的实例名称都必须是唯一的。例如，如果您有一个名为 foo 的 BUDGET (SNOWFLAKE.CORE) 类实例，您无法在同一个架构中创建名为 foo 的 ANOMALY_DETECTION (SNOWFLAKE.ML) 类实例。

例如，要创建异常检测器 my_anomaly_detector 实例，请执行以下语句：

CREATE ANOMALY_DETECTION my_anomaly_detector(
  INPUT_DATA => SYSTEM$REFERENCE('VIEW', 'my_view'),
  TIMESTAMP_COLUMN => 'my_timestamp_column'
  TARGET_COLNAME => 'my_target_column',
  LABEL_COLNAME => ''
);

使用实例¶

创建类的实例后，可以调用该类提供的实例方法。调用方法需要使用感叹号 (!) 字符。! 字符用于对实例取消引用。

例如，要调用异常检测器 my_anomaly_detector 的 DETECT_ANOMALIES 方法，请执行以下语句：

CALL my_anomaly_detector!DETECT_ANOMALIES(
  INPUT_DATA => SYSTEM$REFERENCE('VIEW', 'my_view'),
  TIMESTAMP_COLNAME =>'my_timestamp_column',
  TARGET_COLNAME => 'my_target_column'
);

从返回表格数据的 SQL 类实例方法中选择列¶

某些方法返回表格数据（例如，ANOMALY_DETECTION 和 FORECAST 类中的方法）。要选择和操作这些表格数据，可以在 SELECT 语句的 FROM 子句中调用这些方法。

调用该方法时，请省略 CALL 命令。改为将调用放在括号中，前面加上 TABLE 关键字：

SELECT ... FROM TABLE( <method_name>( <arg> [ , ... <arg> ] ) );

例如，要从异常检测器 my_anomaly_detector 的 DETECT_ANOMALIES 方法返回的表格数据中选择 ts、forecast、和 is_anomaly 列：

SELECT ts, forecast, is_anomaly FROM TABLE(
  my_anomaly_detector!DETECT_ANOMALIES(
    INPUT_DATA => TABLE('my_view'),
    TIMESTAMP_COLNAME =>'my_timestamp_column',
    TARGET_COLNAME => 'my_target_column'
  )
);

如果您传递对查询的引用，则该查询不能引用在引用之外定义的任何公用表表达式。例如，执行以下语句会导致错误，因为查询引用引用了外部 WITH 子句中定义的 my_data：

WITH my_data AS (
  SELECT * FROM my_view
)
SELECT ts, forecast FROM TABLE(
  my_anomaly_detector!DETECT_ANOMALIES(
    INPUT_DATA => TABLE('SELECT * FROM my_data'),
    TIMESTAMP_COLNAME =>'my_timestamp_column',
    TARGET_COLNAME => 'my_target_column'
  )
);

要解决此限制，请将 WITH 子句移到查询引用中：

SELECT ts, forecast FROM TABLE(
  my_anomaly_detector!DETECT_ANOMALIES(
    INPUT_DATA => TABLE('
      WITH my_data AS (
        SELECT * FROM my_view
      )
      SELECT * FROM my_data
    '),
    TIMESTAMP_COLNAME =>'my_timestamp_column',
    TARGET_COLNAME => 'my_target_column'
  )
);

可用类¶

有关可用的 Snowflake 类的列表，请参阅 SQL 类参考。

限制¶

只有 CUSTOM_CLASSIFIER 类的实例支持复制。