Erstellen von Java-UDFs¶

Schreiben des UDF-Handlers in Java¶

Beachten Sie beim Schreiben eines Java-UDF-Handlers die folgenden Anforderungen und Richtlinien.

• Definieren Sie die Klasse als „public“.

• Deklarieren Sie innerhalb der Klasse mindestens eine öffentliche Methode, die als UDF-Handler verwendet werden soll.

  Bei einer Inline-UDF deklarieren Sie nur eine einzige Handler-Methode. Wenn Sie aber beabsichtigen, die Klasse in eine JAR-Datei als vorkompilierte UDF zu packen, können Sie mehrere Handler-Methoden deklarieren und später jede mit der HANDLER-Klausel einer CREATE FUNCTION-Anweisung als Handler spezifizieren.

  Sie können bei Bedarf weitere Methoden deklarieren, die von der Handler-Methode aufgerufen werden.

  Beachten Sie die folgenden Anforderungen und Richtlinien bei jeder Handler-Methode:

  • Deklarieren Sie die Handler-Methode als „public“ (öffentlich), entweder statisch oder nicht-statisch.

    Wenn die Methode nicht statisch ist, muss Ihre Klasse auch einen Konstruktor mit null Argumenten oder überhaupt keinen Konstruktor deklarieren.

    Snowflake übergibt beim Instanziieren der Klasse keine Argumente an den Konstruktor. Wenn der Konstruktor einen Fehler auslöst, wird dieser Fehler zusammen mit der Ausnahmemeldung als Benutzerfehler ausgelöst.

  • Geben Sie einen geeigneten Rückgabetyp an.

    Der Rückgabetyp muss einer der in der Spalte Java Data Type der SQL-Java-Typzuordnungstabelle angegebenen Datentypen sein. Der Rückgabetyp muss mit dem SQL-Datentyp kompatibel sein, der in der RETURNS-Klausel der CREATE FUNCTION-Anweisung angegeben ist.

  • Stellen Sie sicher, dass jedes Argument der Handler-Methode (falls vorhanden) ein Datentyp ist, der in der Spalte Java Data Type der SQL-Java-Typzuordnungstabelle angegeben ist.

    Berücksichtigen Sie bei der Auswahl der Datentypen von Java-Variablen die maximal und minimal möglichen Werte der Daten, die von Snowflake gesendet (und an Snowflake zurückgegeben) werden könnten.

  • Achten Sie in jeder Handler-Methode und den von ihr aufgerufenen Methoden auf die Einhaltung der Snowflake-Einschränkungen für Java-UDFs.

Erstellen der Funktion in Snowflake¶

Die Informationen in diesem Abschnitt gelten für alle Java-UDFs, unabhängig davon, ob der Code inline oder vorkompiliert angegeben wird.

Sie müssen eine CREATE FUNCTION-Anweisung ausführen, bestimmte Aspekte der UDF anzugeben einschließlich:

• Name der UDF.

• Der Name der Java-Methode, die Snowflake als Handler aufrufen soll, wenn die UDF aufgerufen wird.

Der UDF-Name muss nicht mit dem Namen der in Java geschriebenen Handler-Methode übereinstimmen. Die CREATE FUNCTION-Anweisung verknüpft den UDF-Namen mit der Java-Methode, wie in folgender Abbildung gezeigt:

Bei der Wahl des UDF-Namens beachten Sie Folgendes:

• Der Name muss den Regeln für Objektbezeichner folgen.

• Wählen Sie einen Namen, der eindeutig ist, oder folgen Sie den Regeln für Überladen von UDF-Namen.

  Wichtig

  Im Gegensatz zur Überladung bei SQL-UDFs, die zwischen Funktionen sowohl nach der Anzahl als auch nach den Datentypen der Argumente unterscheiden, unterscheiden Java-UDFs Methoden nur nach der Anzahl der Argumente. Wenn zwei Java-Methoden den gleichen Namen und die gleiche Anzahl von Argumenten, aber unterschiedliche Datentypen haben, dann erzeugt der Aufruf einer UDF mit einer dieser Methoden als Handler einen Fehler, der in etwa wie folgt lautet:

  Kann nicht bestimmen, welche Implementierung von Handler „Handlername“ aufgerufen werden soll, da es mehrere Definitionen mit <Anzahl der Argumente> Argumenten in Funktion <Name der UDF> mit Handler <Klassenname>.<Handlername> gibt.

  Wenn ein Warehouse vorhanden ist, wird der Fehler zum Zeitpunkt der Erstellung der UDF erkannt. Andernfalls tritt der Fehler beim Aufruf der UDF auf.

  Das Auflösen auf Basis von Datentypen ist unpraktisch, da einige SQL-Datentypen mehr als einem Java-Datentyp und damit potenziell mehr als einer Java-UDF-Signatur zugeordnet werden können.

Argumente der Handler-Methode werden an die Argumente der UDF über die Position gebunden, nicht über den Namen. Mit anderen Worten: Das erste UDF-Argument wird an das erste Methodenargument übergeben, das zweite UDF-Argument wird an das zweite Methodenargument übergeben, usw.

In den folgenden Beispielen entspricht das SQL-UDF-Argument x dem Java-Methodenargument a, und y entspricht b:

create function add_int_float(x numeric(9, 0), y float)
returns float
language java
handler = 'MyClass.addIntFloat';

public static float addIntFloat(int a, float b) {
  // ...
}

Weitere Informationen zu den Datentypen von Argumenten finden Sie unter Zuordnung von SQL-Java-Datentypen für Parameter und Rückgabetypen.

Es wird empfohlen, mit dem Parameter RUNTIME_VERSION der CREATE FUNCTION-Anweisung die zu verwendende unterstützte Java-Laufzeitversion anzugeben, da sich die Standardversion in Zukunft ändern kann.

Inline-UDFs vs. vorkompilierte UDFs¶

Sie können einen Java-UDF-Handler auf eine der folgenden Arten definieren:

• Vorkompiliert – Sie packen den kompilierten Java-Handler in eine JAR-Datei und speichern diese dort, wo Snowflake sie lesen kann.

  Die CREATE FUNCTION-Anweisung gibt den Speicherort der JAR-Datei an, die den Handler enthält. Vor dem Ausführen von CREATE FUNCTION müssen Sie die JAR-Datei in den Stagingbereich kopieren, aus dem Snowflake die Datei lesen kann.

• Inline – Sie binden den Java-Code mit der UDF-Deklaration selbst ein.

  Die CREATE FUNCTION-Anweisung gibt dann den Java-Quellcode selbst an. Snowflake kompiliert den Quellcode und speichert den kompilierten Code in einer JAR-Datei. Beim Ausführen von CREATE FUNCTION können Sie mit der TARGET_PATH-Klausel einen Speicherort für die resultierende JAR-Datei angeben.

  • Wenn CREATE FUNCTION einen Speicherort für die JAR-Datei angibt, kompiliert Snowflake den Code einmal und behält die JAR-Datei für die zukünftige Verwendung.

  • Wenn CREATE FUNCTION keinen Speicherort für die JAR-Datei angibt, führt Snowflake eine erneute Kompilierung des Codes für jede SQL-Anweisung durch, die die UDF-Anweisung aufruft, und Snowflake bereinigt die JAR-Datei automatisch, nachdem die SQL-Anweisung beendet ist.

Hinzufügen von Abhängigkeiten zum Klassenpfad¶

Wenn Ihr Handler-Code Klassen benötigt, die in externen JAR-Dateien verpackt sind, können Sie diese Abhängigkeiten dem von Snowflake verwalteten Klassenpfad hinzufügen, der für Ihren Handler verfügbar ist. Im Folgenden wird beschrieben, wie JAR-Dateien dem Klassenpfad hinzufügt werden, der für einen Java-UDF Handler sichtbar ist.

1. Erstellen Sie einen Stagingbereich, auf den Ihr Handler zugreifen kann.

   Für UDF-Abhängigkeiten können Sie einen externen Stagingbereich oder eine interne Stagingbereich verwenden. Wenn Sie einen internen Stagingbereich verwenden, muss es sich um einen Benutzer- oder benannten Stagingbereich handeln. Snowflake unterstützt derzeit nicht die Verwendung von Tabellen-Stagingbereichen für UDF-Abhängigkeiten. Weitere Informationen zum Erstellen eines Stagingbereichs finden Sie unter CREATE STAGE. Weitere Informationen zur Auswahl des Typs eines internen Stagingbereichs finden Sie unter Auswahl eines internen Stagingbereichs für lokale Dateien.

2. Kopieren Sie die JAR-Datei mit den Abhängigkeiten in den Stagingbereich.

   Sie können die JAR-Datei von einem lokalen Laufwerk in einen Stagingbereich kopieren, indem Sie den Befehl PUT verwenden. Weitere Informationen zu diesem Befehl finden Sie unter PUT. Weitere Informationen zum Staging von Dateien mit PUT finden Sie unter Staging von Datendateien aus einem lokalen Dateisystem.

3. Verweisen Sie beim Erstellen der UDF auf die JAR-Datei mit den Abhängigkeit.

   Wenn Sie CREATE FUNCTION ausführen, um die UDF zu erstellen, geben Sie Speicherort und Dateipfad/Dateiname im Stagingbereich für alle abhängigen JAR-Dateien als Werte der IMPORTS-Klausel an. Zur Laufzeit fügt Snowflake die JAR-Datei zum Klassenpfad hinzu. Weitere Informationen dazu finden Sie unter CREATE FUNCTION.

   Im folgenden Beispielcode wird eine UDF mit dem Namen my_udf erstellt, die eine my_handler_dependency.jar-Abhängigkeit vom Stagingbereich @mystage angibt.

   CREATE FUNCTION my_udf(i NUMERIC)
     RETURNS NUMERIC
     LANGUAGE JAVA
     IMPORTS = ('@mystage/dependencies/my_handler_dependency.jar')
     HANDLER = 'MyClass.myFunction'
     AS
     $$
       // Handler code omitted.
     $$
   

Erstellen einer Inline-Java-UDF¶

Bei einer Inline-UDF stellen Sie den Java-Quellcode als Teil der CREATE FUNCTION-Anweisung bereit.

Sie fügen den Java-Quellcode in die AS-Klausel ein und umschließen den Code mit einfachen Anführungszeichen oder einem Paar von Dollarzeichen ($$). Möglicherweise ist die Verwendung von doppelten Dollarzeichen einfacher, z. B. wenn der Quellcode eingebettete einfache Anführungszeichen enthält.

Der Code im folgenden Beispiel deklariert eine add-UDF, deren Handler die Methode add in der Klasse TestAddFunc ist.

create function add(x integer, y integer)
returns integer
language java
handler='TestAddFunc.add'
target_path='@~/TestAddFunc.jar'
as
$$
    class TestAddFunc {
        public static int add(int x, int y) {
          return x + y;
        }
    }
$$;

Angenommen, der Java-Quellcode kann mehr als eine Klasse und mehr als eine Methode in einer Klasse enthalten. Dann werden Klasse und Methode für den Aufruf in der HANDLER-Klausel angegeben.

Eine Inline-Java-UDF (wie auch eine vorkompilierte Java-UDF) kann Code in JAR-Dateien aufrufen, die in der IMPORTS-Klausel der CREATE FUNCTION-Anweisung enthalten sind.

Weitere Informationen zur CREATE FUNCTION-Anweisung finden Sie unter CREATE FUNCTION.

Weitere Beispiele finden Sie unter Beispiele für Java-UDF-Handler.

Erstellen einer vorkompilierten Java-UDF¶

Wenn Sie beabsichtigen, einen UDF zu erstellen, die den Speicherort einer vorhandenen JAR-Datei für den Handler angibt, entwickeln Sie den Handler wie folgt:

• Organisieren der Codedateien in einer Hierarchie für das Packen in eine JAR-Datei.

• Kompilieren des Codes und Packen in eine JAR-Datei.

• Kopieren der JAR-Datei mit der Handler-Funktion in einen Stagingbereich, in dem Snowflake die Datei zur Laufzeit lesen kann.