设计 Java UDFs¶

参数和返回类型的 SQL-Java 数据类型映射¶

有关 Snowflake 如何在 Java 与 SQL 数据类型之间转换的信息，请参阅 SQL 与处理程序语言之间的数据类型映射。

TIMESTAMP_LTZ 值和时区¶

Java UDF 在很大程度上与调用它的环境相隔离。但是，时区是从调用环境继承的。如果调用方的会话在调用 Java UDF 之前设置了默认时区，则 Java UDF 具有相同的默认时区。Java UDF 使用与 Snowflake SQL 所用的原生 TIMEZONE 相同的 IANA 时区数据库 (https://www.iana.org/time-zones) 数据（即时区数据库的版本 2021a 中的数据）。

NULL 值¶

Snowflake 支持两个不同的 NULL 值：SQL NULL 和 VARIANT 的 JSON null。（有关 Snowflake VARIANT NULL 的信息，请参阅 NULL 值。）

Java 支持一个 null 值，该值仅适用于非基元数据类型。

Java UDF 的 SQL NULL 实参会转换为 Java null 值，但仅适用于支持 null 的 Java 数据类型。

返回的 Java null 值将转换回 SQL NULL。

实参数组和变量数量¶

Java UDFs 可以接收以下任何 Java 数据类型的数组：

• 字符串

• 布尔

• 双精度

• 浮点

• 整数

• 长整型

• 短整型

传递的 SQL 值的数据类型必须与相应的 Java 数据类型兼容。有关数据类型兼容性的更多信息，请参阅 SQL-Java 数据类型映射。

以下附加规则适用于每种指定的 Java 数据类型：

• 布尔：Snowflake ARRAY 必须仅包含 BOOLEAN 元素，并且不得包含任何 NULL 值。

• int/short/long：Snowflake ARRAY 必须仅包含小数位数为 0 的 定点 元素，并且不得包含任何 NULL 值。

• float/double：Snowflake ARRAY 必须包含以下任一内容：

  • FLOAT 元素。

  • 定点 元素（具有任意小数位数）。

  ARRAY 不能包含任何 NULL 值。

Java 方法可以通过以下两种方式之一接收这些数组：

• 使用 Java 的数组功能。

• 使用 Java 的 *varargs*（可变的实参数量）功能。

在这两种情况下， SQL 代码都必须传递 ARRAY。

跨调用共享状态¶

Snowflake 希望独立处理标量 UDFs。依赖调用间共享的状态可能会导致意外行为。这是因为系统可按任何顺序处理行，并将这些调用分散到多个 JVMs（适用于使用 Java 或 Scala 编写的处理程序）或实例（适用于使用 Python 编写的处理程序）中。

UDFs 应避免在对处理程序方法的调用之间依赖共享状态。但是，在以下两种情况下，可能希望 UDF 存储共享状态：

• 包含不希望对每一行重复的昂贵初始化逻辑的代码。

• 跨行（如缓存）利用共享状态的代码。

如果需要在多行中共享状态，而且状态不会随时间改变，那么可以使用构造函数通过设置实例级变量来创建共享状态。每个实例只执行一次构造函数，而处理程序则每行调用一次，因此当处理程序处理多行时，在构造函数中进行初始化的成本更低。此外，由于构造函数只被调用一次，因此无需编写线程安全的构造函数。

如果 UDF 存储的共享状态发生变化，那么您的代码就必须准备好处理对该状态的并发访问。接下来的两节详细介绍并行性和共享状态。

了解 Java UDF 并行化¶

为了提高性能，Snowflake 可在 JVMs 之间和内部实现并行化。

• 跨多个 JVMs：

  Snowflake 可在 仓库 中的工作线程之间实现并行化。每个工作线程运行一个（或多个） JVMs。这意味着没有全局共享状态。最多只能在单个 JVM 内共享状态。

• 在 JVMs 内：

  • 每个 JVM 可以执行多个线程，这些线程可以并行调用同一实例的处理程序方法。这意味着每个处理程序方法都需要是线程安全的。

  • 如果 UDF 为 IMMUTABLE，并且 SQL 语句对同一行使用相同实参调用 UDF 多次，那么 UDF 对该行的每次调用都会返回相同的值。例如，如果 UDF 为 IMMUTABLE，以下调用会为每行返回两次相同的值。

    select
           my_java_udf(42),
           my_java_udf(42)
        from table1;
    

    Copy

    如果您希望多次调用即使传递相同的实参也能返回独立的值，并且不想声明函数 VOLATILE，那么可以将多个独立的 UDFs 绑定到同一个处理程序方法上。例如：

    1. 使用如下代码，创建一个名为 @java_udf_stage/rand.jar 的 JAR 文件：

       class MyClass {
       
           private double x;
       
           // Constructor
           public MyClass()  {
               x = Math.random();
           }
       
           // Handler
           public double myHandler() {
               return x;
           }
       }
       

       Copy

    2. 创建 Java UDFs，如下所示。这些 UDFs 具有不同的名称，但使用相同的 JAR 文件和该 JAR 文件中相同的处理程序。

       create function my_java_udf_1()
           returns double
           language java
           imports = ('@java_udf_stage/rand.jar')
           handler = 'MyClass.myHandler';
       
       create function my_java_udf_2()
           returns double
           language java
           imports = ('@java_udf_stage/rand.jar')
           handler = 'MyClass.myHandler';
       

       Copy

    3. 以下代码调用了两个 UDFs。UDFs 指向同一 JAR 文件和处理程序。这些调用会创建同一类的两个实例。每个实例返回一个独立的值，因此下面的示例返回两个独立值，而不是两次返回相同的值：

       select
               my_java_udf_1(),
               my_java_udf_2()
           from table1;
       

       Copy

存储 JVM 状态信息¶

避免依赖动态共享状态的一个原因是，行不一定按可预测的顺序进行处理。每次执行 SQL 语句时，Snowflake 都可以更改批处理数、批处理顺序以及批处理中的行顺序。如果将标量 UDF 设计为一行影响后续行的返回值，则每次执行 UDF 时， UDF 都会返回不同的结果。