Überblick über benutzerdefinierte 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. Eine Funktion gibt immer explizit einen Wert zurück, indem sie einen Ausdruck angibt. Sie ist also eine gute Wahl, um einen Wert zu berechnen und zurückzugeben.

Sie können UDFs verwenden, um integrierte Funktionen zu erweitern oder um Berechnungen zu kapseln, die in Ihrer Organisation Standard sind. UDFs, die Sie erstellen, können auf ähnliche Weise wie integrierte Funktionen aufgerufen werden.

Die Logik einer UDF, d. h. sein Handler, wird in einer der unterstützten Sprachen geschrieben. Sobald Sie einen Handler haben, können Sie eine UDF mit einem der verschiedenen in Snowflake enthaltenen Tools erstellen und dann den UDF ausführen.

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.

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

Variationen benutzerdefinierter Funktionen¶

Sie können eine UDF in einer von mehreren Varianten schreiben, je nachdem, welche Eingabe- und Ausgabeanforderungen Ihre Funktion erfüllen muss.

Variation	Beschreibung
Benutzerdefinierte Funktion (UDF)	Auch bekannt als skalare Funktion, gibt für jede Eingabezeile eine Ausgabezeile zurück. Die zurückgegebene Zeile besteht aus einer einzelnen Spalte/Wert.
Benutzerdefinierte Aggregatfunktion (UDAF)	Arbeitet mit Werten über mehrere Zeilen hinweg, um mathematische Berechnungen wie Summe, Durchschnitt, Anzahl, Ermitteln von Minimum- oder Maximumwert, Standardabweichung und Schätzung sowie andere nicht mathematische Operationen auszuführen.
Benutzerdefinierte Tabellenfunktion (UDTF)	Gibt einen tabellarischen Wert für jede Eingabezeile zurück.
Vektorisierte benutzerdefinierte Funktion (UDF)	Empfängt Batches von Eingabezeilen als Pandas DataFrames und gibt Batches von Ergebnissen als Pandas-Arrays oder -Serien zurück.
Vektorisierte benutzerdefinierte Tabellenfunktion (UDTF)	Empfängt Batches von Eingabezeilen als Pandas DataFrames und gibt tabellarische Ergebnisse zurück.

Unterstützte Sprachen und Tools¶

Sie können und UDFs (und andere Snowflake-Entitäten) mit einem von mehreren Tools erstellen und verwalten, je nachdem, wie Sie am liebsten arbeiten.

Sprache	Ansatz	Unterstützung
SQL Mit Handler in Java, JavaScript, Python, Scala, oder SQL	Schreiben Sie SQL-Code in Snowflake, um Snowflake-Entitäten zu erstellen und zu verwalten. Schreiben Sie die Logik der Funktion in einer der unterstützten Handler-Sprachen.	Java: UDF, UDTF JavaScript: UDF, UDTF Python: UDF, UDAF, UDTF, Vektorisiert UDF, Vektorisiert UDTF Scala: UDF SQL: UDF, UDTF
Java, Python oder Scala Snowpark API	Schreiben Sie im Client Code für Operationen, die zur Verarbeitung an Snowflake weitergeleitet werden.	Java: UDF, UDTF Python: UDF, UDAF, UDTF, Vektorisiert UDF oder UDTF Scala: UDF, UDTF
Befehlszeilenschnittstelle Snowflake CLI	Verwenden Sie die Befehlszeile, um Snowflake-Entitäten zu erstellen und zu verwalten, indem Sie Eigenschaften als Eigenschaften von JSON-Objekten angeben.	Verwalten von Snowflake-Objekten
Python Snowflake-Python-API	Führen Sie auf dem Client Befehle aus, um die Funktion mit Python zu erstellen und schreiben Sie den Handler der Funktion in einer der unterstützten Handler-Sprachen.	Verwalten benutzerdefinierter Funktionen (UDFs)
REST Snowflake REST API	Stellen Sie Anfragen an RESTful-Endpunkte, um Snowflake Entitäten zu erstellen und zu verwalten.	Benutzerdefinierte Funktionen verwalten

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

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.
Wenn Sie die Funktion CURRENT_DATABASE oder CURRENT_SCHEMA im Handler-Code der UDF angeben, gibt die Funktion die Datenbank oder das Schema zurück, die/das die UDF enthält, und nicht die Datenbank oder das Schema, die/das für die Sitzung verwendet wird.

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.9'
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

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 und Tools.
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, Ablaufverfolgung und Metriken:: Sie können Code-Aktivitäten aufzeichnen, indem Sie Protokollmeldungen, Ablaufverfolgungsereignisse und Metrikdaten 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 Erteilen von Berechtigungen für benutzerdefinierte Funktionen.

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 mit der Funktionsdefinition oder als Code außerhalb der Definition angeben, z. B. als Code, der gepackt und in einen Stagingbereich kopiert wird.

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