为使用 SQL 创建的存储过程编写 Java 处理程序¶

为存储过程编写 Java 处理程序¶

1. 确保您的环境满足 先决条件。

2. 如果您在本地开发，请 设置您的环境以使用 Snowpark。

3. 选择 是内联部署还是在暂存区 部署您的处理程序。

4. 遵循处理程序 类、方法 和 性能 的指南。

5. 实现对 数据访问、文件读取、返回表格数据 以及 日志记录和跟踪 等功能的支持。

6. 使您的代码 依赖项在 Snowflake 上可用。

7. 创建存储过程 时，包含内联的或从暂存区导入的处理程序代码。

先决条件¶

您必须使用版本 1.3.0 或更新版本的 Snowpark 库。

如果要编写存储过程，则必须编译类以在以下 Java 版本之一中运行：

• 11.x

• 17.x

为 Snowpark 设置开发环境¶

如果您在本地开发代码，请设置您的开发环境以使用 Snowpark 库。请参阅 为 Snowpark Java 设置开发环境。

构建处理程序代码¶

您可以使处理程序源代码与创建过程的 SQL 保持一致，或者将处理程序编译的结果保留在单独的位置，并从 SQL 中引用它。有关更多信息，请参阅 将处理程序代码保持内联或保留在暂存区。

有关构建用于过程的处理程序源代码的更多信息，请参阅 打包处理程序代码。

处理程序类的指南¶

编写类时，请注意以下事项：

• 类和方法不得受保护或私有。

• 如果该方法不是静态的，并且您想要定义构造函数，请为类定义一个零实参构造函数。Snowflake 在初始化时调用此零实参构造函数来为类创建实例。

• 可以为同一类中的不同存储过程定义不同的方法。

处理程序方法指南¶

为存储过程编写方法时，请注意以下事项：

• 将 Snowpark Session 对象指定为方法的第一个实参。

  调用存储过程时，Snowflake 会自动创建一个 Session 对象并将其传递给存储过程。（您不能自行创建 Session 对象。）

• 对于其余实参和返回值，请使用与 Snowflake 数据类型 相对应的 Java 类型。

• 方法必须返回一个值。对于使用 Java 编写的存储过程，返回值是必需的。

• 存储过程执行将超时，除非代码活动重置计时器。具体而言，超时计时器通过代码与数据之间的交互（包括文件操作、查询和迭代结果集）重置。

• 当您运行来自过程处理程序中的 异步子作业 时，不支持“发后即忘”。

  换句话说，如果处理程序发出的子查询在父存储过程作业完成时仍在运行，子作业就会自动取消。

处理错误¶

您可以使用正常的 Java 异常处理技术来捕获处理程序代码中的错误。

如果方法内部出现未捕获的异常，Snowflake 会引发一个包含异常堆栈跟踪的错误。启用 记录未处理异常 后，Snowflake 会在事件表中记录有关未处理异常的数据。

处理程序性能和安全指南¶

为确保代码在 Snowflake 上运行良好，请遵循以下指南：

• 限制消耗的内存量。

  Snowflake 根据所需的内存量对方法进行了限制。有关如何避免消耗过多内存的更多信息，请参阅 设计保持在 Snowflake 施加的约束范围内的处理程序。

• 编写线程安全代码。

  确保您的处理程序方法或函数是线程安全的。

• 了解安全限制。

  处理程序代码在受限引擎中运行，因此请务必遵循 UDFs 和过程的安全实践 中所述的规则。

• 决定使用所有者权限还是调用方权限。

  在计划编写存储过程时，请考虑希望存储过程使用 调用方权限还是所有者权限 运行。

• 请记住存储过程的超时行为。

  存储过程执行将超时，除非代码活动重置计时器。具体而言，超时计时器通过代码与数据之间的交互（包括文件操作、查询和迭代结果集）重置。

为代码提供依赖项¶

如果处理程序代码依赖在处理程序之外（如 JAR 文件中的类）定义的代码或依赖资源文件，则可以通过将这些依赖项上传到暂存区来为代码提供这些依赖项。创建过程 时，可以使用 IMPORTS 子句引用这些依赖项。

有关更多信息，请参阅 为代码提供依赖项。