Entwerfen von Java-UDFs¶

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

Die folgende Tabelle zeigt die Typzuordnungen zwischen SQL und Java. Diese Zuordnungen gelten im Allgemeinen sowohl für die Argumente, die an die Java-UDF übergeben werden, als auch für die Werte, die von der UDF zurückgegeben werden. Es gibt jedoch einige Ausnahmen, die in Fußnoten ausgeführt werden.

Einige SQL-Datentypen (z. B. NUMBER) sind mit mehreren Java-Datentypen kompatibel (z. B. int, long). In diesen Fällen können Sie einen beliebigen Java-Datentyp verwenden, der genügend Kapazität hat, um die tatsächlich zu übergebenden Werte aufzunehmen. Wenn Sie einen SQL-Wert an einen inkompatiblen Java-Datentyp übergeben (oder umgekehrt), gibt Snowflake einen Fehler aus.

1(1,2)

Das Format stimmt mit dem Internet (RFC)-Zeitstempelformat DY, DD MON YYYY HH24:MI:SS TZHTZM überein, wie unter Zeitstempelformate beschrieben. Wenn ein Zeitzonenversatz (die TZHTZM-Komponente) vorhanden ist, handelt es sich in der Regel um Ziffern (z. B. steht -0700 für 7 Stunden hinter UTC). Wenn der Zeitzonenversatz Z (für „Zulu“) anstelle von Ziffern angegeben wird, ist das gleichbedeutend mit „+0000“ (UTC).

2

Das Format stimmt mit dem Internet (RFC)-Zeitstempelformat DY, DD MON YYYY HH24:MI:SS überein, wie unter Zeitstempelformate beschrieben. Wenn auf die Zeichenfolge ein Leerzeichen und Z (für „Zulu“) folgt, wird der Versatz explizit mit „0000“ (UTC) angegeben.

3(1,2,3,4,5,6,7,8)

Obwohl Snowflake Zeitwerte mit Nanosekundengenauigkeit speichern kann, bietet die java.sql.time-Bibliothek nur Millisekundengenauigkeit. Die Konvertierung zwischen Snowflake- und Java-Datentypen kann die effektive Genauigkeit auf Millisekunden reduzieren.

4(1,2,3,4,5,6)

Diese Typzuordnung wird bei der Konvertierung von SQL-Argumenten nach Java unterstützt, aber nicht bei der Konvertierung von Java-Rückgabetypen in SQL-Typen.

5

Java verfügt nicht über einen eigenen Datentyp für geographische Daten. Der Geography-Datentyp, auf den hier Bezug genommen wird, ist eine Klasse im Snowpark-Paket. Weitere Informationen dazu finden Sie unter Unterstützte Typen aus dem Snowpark-Paket.

Unterstützte Typen aus dem Snowpark-Paket¶

In einer benutzerdefinierten Funktion können Sie eine bestimmte Teilmenge von Typen verwenden, die im Snowpark-Java-Paket von Snowflake enthalten sind. Obwohl diese Typen für die Verwendung im Snowpark-Code gedacht sind, können einige davon auch in UDFs verwendet werden, da sie großen praktischen Wert haben. (Weitere Informationen zu Snowpark finden Sie in der Snowpark-Dokumentation).

Die in der folgenden Tabelle aufgeführten Snowpark-Typen werden im UDF-Code unterstützt. Sie können keine anderen Snowpark-Typen in UDF-Code verwenden, da diese dort nicht unterstützt werden.

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 SQL-Java-Datentypen für Parameter und Rückgabetypen.

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.

Speicher¶

Vermeiden Sie einen zu hohen Verbrauch von Speicher.

• Große Datenwerte (typischerweise BINARY-, lange VARCHAR- oder große ARRAY- oder OBJECT- oder VARIANT-Datentypen) benötigen viel Arbeitsspeicher.

• Eine zu große Stapeltiefe kann eine große Menge an Speicher verbrauchen. Snowflake hat einfache Funktionsaufrufe mit einer Verschachtelungstiefe von 50 Ebenen ohne Fehler getestet. Die praktische Maximalgrenze hängt davon ab, wie viele Informationen im Stapel abgelegt werden.

UDFs geben einen Fehler zurück, wenn sie zu viel Speicher verbrauchen. Das jeweilige Limit kann sich ändern.

Zeit¶

Vermeiden Sie Algorithmen, die pro Aufruf sehr viel Zeit benötigen.

Wenn eine UDF-Anweisung zu lange dauert, bricht Snowflake die SQL-Anweisung ab und gibt einen Fehler an den Benutzer zurück. Dieses Limit begrenzt die Auswirkungen (und Kosten) von Fehlern wie Endlosschleifen.

Bibliotheken¶

Obwohl Ihre Java-Methode Klassen und Methoden aus Standard-Java-Bibliotheken verwenden kann, deaktivieren die Sicherheitsrestriktionen von Snowflake einige Funktionen, wie z. B. das Schreiben in Dateien. Einzelheiten zu Bibliothekseinschränkungen finden Sie im Abschnitt Einsetzen von bewährten Sicherheitsmethoden.

Einführung¶

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, da das System Zeilen in beliebiger Reihenfolge verarbeiten und diese Aufrufe auf mehrere JVMs verteilen kann. 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;
    

    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;
           }
       }
       

    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';
       

    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;
       

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.