Übersicht zu benutzerdefinierten Funktionen¶

Mit benutzerdefinierten Funktionen (UDFs) können Sie das System erweitern, um Operationen auszuführen, die nicht über die integrierten, systemdefinierten Funktionen von Snowflake verfügbar sind. Sobald Sie eine UDF erstellt haben, können Sie diese unbegrenzt wiederverwenden.

UDFs sind nur eine mögliche Option, um Snowflake zu erweitern. Weitere Informationen dazu finden Sie unter:

Bemerkung

Eine UDF ist wie eine gespeicherte Prozedur, jedoch unterscheiden sich beide in wichtigen Punkten. Weitere Informationen dazu finden Sie unter Entscheidung über das Schreiben einer gespeicherten Prozedur oder einer benutzerdefinierten Funktion.

Unter diesem Thema:

Was ist eine benutzerdefinierte Funktion (UDF)?¶

Eine benutzerdefinierte Funktion (UDF) ist eine Funktion, die Sie definieren, damit Sie sie von SQL aus aufrufen können. Wie bei integrierten Funktionen, die von SQL aus aufgerufen werden können, kann die Logik einer UDF die Funktionalität von SQL erweitern oder optimieren. Eine UDF bietet auch die Möglichkeit, Funktionalität zu kapseln, sodass Sie diese an mehreren Stellen im Code wiederholt aufrufen können.

Die Logik einer UDF, d. h. sein Handler, wird in einer der unterstützten Sprachen geschrieben. Sobald der Handler verfügbar ist, können Sie mit dem Befehl CREATE FUNCTION eine UDF erstellen und anschließend mit einer SELECT-Anweisung die UDF aufrufen.

Skalare und tabellarische Funktionen¶

Sie können einen UDF schreiben, die einen einzelnen Wert (eine skalare UDF) oder einen tabellarischen Wert (eine benutzerdefinierte Tabellenfunktion oder UDTF) zurückgibt.

Eine skalare Funktion (UDF) gibt für jede Eingabezeile genau eine Ausgabezeile zurück. Die zurückgegebene Zeile besteht aus einer einzelnen Spalte/Wert.
Eine tabellarische Funktion (UDTF) gibt für jede Eingabezeile einen tabellarischen Wert zurück. Im Handler einer UDTF schreiben Sie Methoden, die mit einer von Snowflake benötigten Schnittstelle konform sind. Diese Methoden führen Folgendes aus:
- Verarbeiten jeder Zeile einer Partition (erforderlich).
- Initialisieren des Handlers einmal für jede Partition (optional).
- Abschließen der Verarbeitung jeder Partition (optional).
Die Namen der Methoden variieren je nach Sprache des Handlers. Eine Liste der unterstützten Sprachen finden Sie unter Unterstützte Sprachen.

Hinweise¶

Wenn eine Abfrage eine UDF aufruft, um auf Stagingdateien zuzugreifen, und die SQL-Anweisung außerdem eine Ansicht abfragt, die eine beliebige UDF oder UDTF aufruft, unabhängig davon, ob die Funktion in der Ansicht auf Stagingdateien zugreift oder nicht, dann schlägt die Operation mit einem Benutzerfehler fehl.
UDTFs können mehrere Dateien parallel verarbeiten. UDFs verarbeitet Dateien derzeit seriell. Als Problemumgehung gruppieren Sie Zeilen in einer Unterabfrage mit der GROUP BY-Klausel. Ein Beispiel dazu finden Sie unter CSV-Datei mit einer UDTF verarbeiten.
Wenn Stagingdateien, auf die in einer Abfrage verwiesen wird, geändert oder gelöscht werden, während die Abfrage ausgeführt wird, führt der Funktionsaufruf zu einem Fehler.

Erste Schritte¶

Unter Quickstart: Erste Schritte mit benutzerdefinierten SQL-Funktionen finden Sie ein Tutorial, in dem Sie eine UDTF mit einem in SQL geschriebenen Handler schreiben.

UDF-Beispiel¶

Der Code im folgenden Beispiel erstellt eine UDF namens addone mit einem in Python geschriebenen Handler. Die Handler-Funktion ist addone_py. Diese UDF gibt einen int-Wert zurück.

CREATE OR REPLACE FUNCTION addone(i int)
RETURNS INT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
HANDLER = 'addone_py'
as
$$
def addone_py(i):
  return i+1
$$;

Copy

Der Code im folgenden Beispiel führt die UDF namens addone aus.

SELECT addone(3);

Copy

Unterstützte Sprachen¶

Sie schreiben den Handler einer Funktion, d. h. dessen Logik, in einer der unterstützten Programmiersprachen. Jede Sprache ermöglicht es Ihnen, Daten im Rahmen der durch die Sprache und ihrer Laufzeitumgebung vorgegebenen Einschränkungen zu bearbeiten. Unabhängig von der Sprache des Handlers wird die Prozedur selbst auf die gleiche Weise erstellt, wie bei Verwendung von SQL durch Angabe des Handlers und der Sprache des Handlers.

Sie können einen Handler in einer der folgenden Sprachen schreiben:

Sprache	Entwicklerhandbücher
Java	Java-UDFs Java-UDTFs
JavaScript	JavaScript-UDFs JavaScript-UDTFs
Python	Python-UDFs Python-UDTFs
Scala	Scala-UDFs
SQL	SQL-UDFs SQL-UDTFs

Wahl der Sprache¶

Sie schreiben den Handler einer UDF, d. h. dessen Logik, in einer der unterstützten Programmiersprachen. Jede Sprache ermöglicht es Ihnen, Daten im Rahmen der durch die Sprache und ihrer Laufzeitumgebung vorgegebenen Einschränkungen zu bearbeiten.

Kriterien für die Wahl einer bestimmte Sprache:

Sie haben bereits Code in dieser Sprache.

Wenn Sie z. B. bereits eine Java-Methode haben, die als Handler funktioniert, und das Objekt der Methode in einer JAR-Datei enthalten ist, können Sie die JAR-Datei in einen Stagingbereich kopieren, den Handler als Klasse und Methode angeben und dann als Sprache Java angeben.
Die Sprache bietet Möglichkeiten, die andere nicht bieten.
Die Sprache verfügt über Bibliotheken, die Ihnen bei der gewünschten Verarbeitung helfen können.

Bei der Wahl einer Sprache sollten Sie auch Folgendes beachten:

Unterstützte Handler-Speicherorte. Nicht alle Sprachen unterstützen das Verweisen auf einen Handler in einem Stagingbereich (der Handler-Code muss stattdessen inline sein). Weitere Informationen dazu finden Sie unter Speichern von Handler-Code inline oder in einem Stagingbereich.
Ob der Handler zu einem UDF führt, der freigegeben werden kann. Eine UDF, die freigegeben werden kann, kann mit dem Snowflake-Feature Secure Data Sharing verwendet werden.

Sprache	Speicherort des Handlers	Freigabe
Java	Inline oder Staging	Nein [1]
JavaScript	Inline	Ja
Python	Inline oder Staging	Nein [2]
Scala	Inline oder Staging	Nein [3]
SQL	Inline	Ja

Entwicklerhandbücher¶

Richtlinien und Einschränkungen¶

Snowflake-Einschränkungen:: Sie können die Stabilität innerhalb der Snowflake-Umgebung sicherstellen, indem die Snowflake-Einschränkungen beim Entwickeln berücksichtigen. Weitere Informationen dazu finden Sie unter Entwerfen von Handlern unter Berücksichtigung der Snowflake-bedingten Einschränkungen.
Namensgebung:: Achten Sie darauf, Funktionen so zu benennen, dass es nicht zu Kollisionen mit anderen Funktionen kommt. Weitere Informationen dazu finden Sie unter Benennen und Überladen von Prozeduren und UDFs.
Argumente:: Geben Sie die Argumente an, und geben Sie an, welche Argumente optional sind. Weitere Informationen dazu finden Sie unter Definieren von Argumenten für UDFs und gespeicherte Prozeduren.
Zuordnung von Datentypen:: Für jede Handler-Sprache gibt es einen separaten Satz von Zuordnungen zwischen den Datentypen der Sprache und den SQL-Typen, die für Argumente und Rückgabewerte verwendet werden. Weitere Informationen zur Zuordnung in den einzelnen Sprachen finden Sie unter Zuordnung von Datentypen zwischen SQL und Handler-Sprachen.

Schreiben von Handlern¶

Sprachen des Handlers:: Sprachspezifische Informationen zum Schreiben eines Handlers finden Sie unter Unterstützte Sprachen.
Externer Netzwerkzugriff:: Mit externem Netzwerkzugriff können Sie auf externe Netzwerkstandorte zugreifen. Sie können einen sicheren Zugriff auf bestimmte Netzwerkstandorte außerhalb von Snowflake erstellen und diesen Zugriff dann innerhalb des Handler-Codes verwenden.
Protokollierung und Ablaufverfolgung:: Sie können Code-Aktivitäten erfassen, indem Sie Protokollmeldungen und Ablaufverfolgungsereignisse aufzeichnen und die Daten in einer Datenbank speichern, die Sie später abfragen können.

Sicherheit¶

Mit einer UDF oder UDTF können Sie den Objekten die Berechtigungen erteilen, die diese benötigen, um bestimmte SQL-Aktionen auszuführen. Weitere Informationen dazu finden Sie unter Granting Privileges for User-Defined Functions.

Bei Funktionen müssen bestimmte Sicherheitsaspekte wie bei gespeicherten Prozeduren berücksichtigt werden. Weitere Informationen dazu finden Sie unter:

Sie können dazu beitragen, dass der Handler-Code einer Prozedur sicher ausgeführt wird, indem Sie die unter Sicherheitsverfahren für UDFs und Prozeduren beschriebenen bewährten Methoden befolgen.
Stellen Sie sicher, dass sensible Informationen vor Benutzern verborgen bleiben, die keinen Zugriff darauf haben sollten. Weitere Informationen dazu finden Sie unter Schutz sensibler Informationen mit sicheren UDFs und gespeicherten Prozeduren.

Bereitstellen von Handler-Code¶

Beim Erstellen einer Funktion können Sie deren Handler, der die Funktionslogik implementiert, als Inline-Code in der CREATE FUNCTION-Anweisung angeben oder als Code außerhalb der Anweisung als kompilierten Code, der gepackt und in einen Stagingbereich kopiert wird.

Weitere Informationen dazu finden Sie unter Speichern von Handler-Code inline oder in einem Stagingbereich.

Funktionen erstellen und aufrufen¶

Sie verwenden SQL, um eine benutzerdefinierte Funktion zu erstellen und aufzurufen.

Um eine Funktion zu erstellen, führen Sie die Anweisung CREATE FUNCTION aus und geben dabei den Handler der Funktion an. Weitere Informationen dazu finden Sie unter Erstellen einer UDF.
Um eine Funktion aufzurufen, führen Sie eine SQL-SELECT-Anweisung aus, die die Funktion als Parameter angibt. Weitere Informationen dazu finden Sie unter Aufrufen einer UDF.