Entwerfen von Java-UDFs¶

Zuordnung von SQL-Java-Datentypen für Parameter und Rückgabetypen¶

Informationen dazu, wie Snowflake zwischen Java- und SQL-Datentypen konvertiert, finden Sie unter Zuordnung von Datentypen zwischen SQL und Handler-Sprachen.

TIMESTAMP_LTZ-Werte und Zeitzonen¶

Ein Java-UDF ist weitgehend isoliert von der Umgebung, in der sie aufgerufen wird. Die Zeitzone wird jedoch von der aufrufenden Umgebung geerbt. Wenn die Sitzung des Aufrufers vor dem Aufruf der Java-UDF eine Standardzeitzone eingestellt hat, dann hat die Java-UDF die gleiche Standardzeitzone. Die Java-UDF verwendet dieselben Daten der IANA-Zeitzonendatenbank, die auch von der nativen TIMEZONE-Funktion in Snowflake SQL verwendet wird (d. h. Daten aus Release 2021a der Zeitzonendatenbank).

NULL-Werte¶

Snowflake unterstützt zwei verschiedene NULL-Werte: SQL NULL und VARIANT JSON null. (Weitere Informationen zu Snowflake VARIANT NULL finden Sie unter NULL-Werte.)

Java unterstützt einen null-Wert, der nur für nicht primitive Datentypen gilt.

Ein SQL-NULL-Argument für eine Java-UDF wird in den Java null-Wert übersetzt, aber nur für Java-Datentypen, die null unterstützen.

Ein zurückgegebener Java null-Wert wird in SQL NULL zurückübersetzt.

Arrays und variable Anzahl von Argumenten¶

Java-UDFs können Arrays von jedem der folgenden Java-Datentypen erhalten:

• String

• boolean

• double

• float

• int

• long

• short

Der Datentyp von übergebenen SQL-Werten muss mit dem entsprechenden Java-Datentyp kompatibel sein. Weitere Informationen zur Datentypkompatibilität finden Sie unter Zuordnung von Datentypen zwischen SQL und Java.

Die folgenden zusätzlichen Regeln gelten für jeden der angegebenen Java-Datentypen:

• boolean: Das Snowflake-ARRAY darf nur BOOLEAN-Elemente und keine NULL-Werte enthalten.

• int/short/long: Das Snowflake-ARRAY darf nur Festkomma-Elemente mit einer Skalierung von 0 enthalten und auch keine NULL-Werte.

• float/double: Das Snowflake-ARRAY muss enthalten:

  • FLOAT-Elemente oder

  • Festkomma-Elemente (mit beliebiger Skalierung).

  Das ARRAY darf keine NULL-Werte enthalten.

Java-Methoden können diese Arrays auf eine von zwei Arten erhalten:

• Verwendung der Array-Funktion von Java.

• Verwendung der Java-Funktion varargs (variable Anzahl von Argumenten).

In beiden Fällen muss Ihr SQL-Code ein ARRAY übergeben.

Gemeinsamer Zustand für alle Aufrufe (Shared State)¶

Snowflake erwartet, dass skalare UDFs unabhängig verarbeitet werden. Wenn Sie sich zwischen Aufrufen auf einen gemeinsamen Zustand verlassen, kann dies zu unerwartetem Verhalten führen. Dies liegt daran, dass das System Zeilen in beliebiger Reihenfolge verarbeiten kann und die Aufrufe auf mehrere JVMs (für in Java oder Scala geschriebene Handler) oder Instanzen (für in Python geschriebene Handler) verteilt werden.

Bei UDFs sollte es vermieden werden, dass sich beim Aufrufen der Handler-Methode auf einen gemeinsamen Zustand verlassen wird. Es gibt jedoch zwei Situationen, in denen Sie möglicherweise möchten, dass eine UDF einen gemeinsamen Zustand speichert:

• Code, der teure Initialisierungslogik enthält, die nicht bei jeder Zeile wiederholt werden soll.

• Code, der einen gemeinsamen Zustand über Zeilen hinweg nutzt, z. B. als Cache.

Wenn Sie den Zustand über mehrere Zeilen hinweg gemeinsam nutzen müssen und sich dieser Zustand im Laufe der Zeit nicht ändert, dann verwenden Sie einen Konstruktor, um den gemeinsamen Zustand durch das Einstellen von Variablen auf Instanzenebene zu erstellen. Der Konstruktor wird nur einmal pro Instanz ausgeführt, während der Handler einmal pro Zeile aufgerufen wird, sodass die Initialisierung im Konstruktor günstiger ist, wenn ein Handler mehrere Zeilen verarbeitet. Und da der Konstruktor nur einmal aufgerufen wird, muss er nicht thread-sicher geschrieben werden.

Wenn Ihre UDF einen gemeinsamen Zustand speichert, der sich ändert, muss Ihr Code darauf vorbereitet sein, den gleichzeitigen Zugriff mit diesem Zustand zu verarbeiten. In den nächsten beiden Abschnitten finden Sie weitere Informationen zur Parallelität und zum gemeinsamen Zustand.

Erläuterungen zur Java-UDF-Parallelisierung¶

Um die Verarbeitungsleistung zu verbessern, nutzt Snowflake die Parallelisierung sowohl zwischen mehrere JVMs als auch innerhalb von JVMs.

• Mehrere JVMs:

  Snowflake parallelisiert mehrere Ausführungen in einem Warehouse. Jede Ausführung nutzt eine (oder mehrere) JVMs. Dies bedeutet, dass es keinen globalen gemeinsamen Zustand gibt. Der Zustand kann höchstens innerhalb einer einzelnen JVM gemeinsam genutzt werden.

• Innerhalb von JVMs:

  • Jede JVM kann mehrere Threads ausführen, die parallel die Handler-Methode der gleichen Instanz aufrufen können. Das bedeutet, dass jede Handler-Methode thread-sicher sein muss.

  • Wenn eine UDF mit IMMUTABLE eingerichtet ist und eine SQL-Anweisung diese UDF mehr als einmal mit denselben Argumenten für dieselbe Zeile aufruft, dann gibt die UDF bei jedem Aufruf für diese Zeile den gleichen Wert zurück. Im Folgenden wird z. B. zweimal derselbe Wert für jede Zeile zurückgegeben, wenn die UDF mit IMMUTABLE eingerichtet ist:

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

    Copy

    Wenn Sie möchten, dass mehrere Aufrufe unabhängige Werte zurückgeben, auch wenn die gleichen Argumente übergeben werden, und wenn Sie nicht die Funktion VOLATILE deklarieren möchten, dann binden Sie mehrere separate UDFs an die gleiche Handler-Methode. Beispiel:

    1. Erstellen Sie eine JAR-Datei mit dem Namen @java_udf_stage/rand.jar mit Code:

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

       Copy

    2. Erstellen Sie die Java-UDFs wie unten gezeigt. Diese UDFs haben unterschiedliche Namen, verwenden aber die gleiche JAR-Datei und innerhalb dieser JAR-Datei den gleichen Handler.

       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. Der folgende Code ruft beide UDFs auf. Die UDFs verweisen auf die gleiche JAR-Datei und den gleichen Handler. Diese Aufrufe erstellen zwei Instanzen der gleichen Klasse. Jede Instanz gibt einen unabhängigen Wert zurück, sodass das folgende Beispiel zwei unabhängige Werte zurückgibt, anstatt zweimal denselben Wert zu liefern:

       select
               my_java_udf_1(),
               my_java_udf_2()
           from table1;
       

       Copy

Speichern von JVM-Statusinformationen¶

Ein Grund, sich nicht auf einen dynamischen gemeinsamen Zustand zu verlassen, besteht darin, dass Zeilen nicht unbedingt in einer vorhersehbaren Reihenfolge verarbeitet werden. Bei jeder Ausführung einer SQL-Anweisung kann Snowflake die Anzahl der Batches, die Reihenfolge, in der die Batches verarbeitet werden, und die Reihenfolge der Zeilen innerhalb eines Batches variieren. Wenn eine skalare UDF so gestaltet ist, dass eine Zeile den Rückgabewert einer nachfolgenden Zeile beeinflusst, dann kann die UDF bei jeder Ausführung unterschiedliche Ergebnisse zurückgeben.