Einführung in Java-UDFs

Sie können den Handler für eine benutzerdefinierte Funktion (UDF) in Java schreiben. Unter den Themen in diesem Abschnitt wird beschrieben, wie Sie einen Java-Handler entwerfen und schreiben. Außerdem werden Beispiele bereitgestellt.

Eine Einführung in UDFs, einschließlich einer Liste der Sprachen, in denen Sie einen UDF-Handler schreiben können, finden Sie unter Übersicht zu benutzerdefinierten Funktionen.

Sobald der Handler verfügbar ist, erstellen Sie die UDF mit SQL. Weitere Informationen zur Verwendung von SQL für das Erstellen oder Aufrufen einer UDF finden Sie unter Erstellen einer UDF bzw. Aufrufen einer UDF.

Snowflake unterstützt derzeit das Schreiben von UDFs mit den folgenden Java-Versionen:

  • 11.x

  • 17.x (Dieses Feature steht allen Konten als Vorschau zur Verfügung.)

Bemerkung

Informationen zu Einschränkungen bezüglich Java-UDF-Handlern finden Sie unter Java-UDF-Einschränkungen.

Unter diesem Thema:

Funktionsweise eines Java-Handlers

Wenn ein Benutzer eine UDF aufruft, übergibt der Benutzer den Namen und die Argumente der UDF an Snowflake. Snowflake ruft den zugehörigen Handler-Code (ggf. mit Argumenten) auf, um die Verarbeitungslogik der UDF auszuführen. Die Handler-Methode gibt dann die Ausgabe an Snowflake zurück, und Snowflake gibt die Ausgabe an den Client zurückgibt.

Für jede Zeile, die an eine UDF übergeben wird, gibt UDF entweder einen Einzelwert oder, falls als Tabellenfunktion definiert, eine Menge von Zeilen zurück.

Java-UDFs können sowohl neuen Code als auch Aufrufe bestehender Bibliotheken enthalten, was sowohl Flexibilität als auch die Wiederverwendung von Code ermöglicht. Wenn Sie z. B. bereits Datenanalysecode in Java haben, dann können Sie diesen wahrscheinlich in eine Java-UDF einbinden.

Nachfolgend finden Sie eine vereinfachte Darstellung des Datenflusses:

UDF-Datenfluss

Beispiel

Der Code im folgenden Beispiel erstellt eine UDF namens echo_varchar mit der Handler-Methode TestFunc.echoVarchar. Die Java-Argumente und -Rückgabetypen werden von Snowflake gemäß den unter Zuordnung von Datentypen zwischen SQL und Java beschriebenen Zuordnungen in und aus SQL konvertiert.

create or replace function echo_varchar(x varchar)
returns varchar
language java
called on null input
handler='TestFunc.echoVarchar'
target_path='@~/testfunc.jar'
as
'class TestFunc {
  public static String echoVarchar(String x) {
    return x;
  }
}';
Copy

Hinweise zum Entwurf

Beachten Sie beim Entwerfen eines effizienten Handlers die folgenden Hinweise.

Codieren von Handlern

Unter den folgenden Themen wird von den Grundlagen bis zu detaillierten Beispielen das Schreiben eines UDF-Handlers in Java erläutert.

  • Java-Klassendefinition. Die Logik einer UDF wird in eine Java-Klasse geschrieben. Weitere Informationen dazu, wie Snowflake mit Ihrem Code interagiert, finden Sie unter Entwerfen der Klasse.

  • Fehlerbehandlung. Informationen dazu, wie Snowflake von Handlern generierte Fehler behandelt, finden Sie unter Fehlerbehandlung.

  • Tabellarische Rückgabewerte. Sie können sowohl tabellarische Werte als auch skalare (Einzel-)Werte aus einer UDF zurückgeben. Informationen zum Schreiben eines Handlers, der tabellarische Werte zurückgibt, finden Sie unter Tabellarische Java-UDFs (UDTFs).

  • Protokollierung und Ereignisablaufverfolgung. Informationen zum Erfassen von Protokoll- und Ablaufverfolgungsdaten während der Ausführung Ihres Handler-Codes finden Sie unter Übersicht zu Protokollierung und Ablaufverfolgung.

  • Abhängigkeiten. Sie können Ihrem Code zur Laufzeit Abhängigkeiten zur Verfügung stellen, indem Sie diese in einen Stagingbereich hochladen. Weitere Informationen dazu finden Sie unter Abhängigkeiten für Code zur Verfügung stellen.

  • Organisation von Handler-Dateien. Wenn Sie beabsichtigen, kompilierten Handler-Code in eine JAR-Datei zu packen, organisieren und erstellen Sie Ihren Code mithilfe unter Organisieren Ihrer Dateien bereitgestellten Vorschläge.

  • Codebeispiele. Zahlreiche Beispiele für Handler in Java finden Sie unter Beispiele für Java-UDF-Handler.