Ü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, während der Ausführung der Abfrage geändert oder gelöscht werden, führt der Funktionsaufruf zu einem Fehler.

  • Wenn die UDF-Definition die Funktion CURRENT_DATABASE oder CURRENT_SCHEMA aufruft, ergibt die Funktion die Datenbank oder das Schema, in der/dem die UDF enthalten ist, und nicht die Datenbank oder das Schema für die Sitzung, die Sie mit einem USE <Objekt>-Befehl angeben oder mit der Kontextauswahl in Snowsight auswählen.

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

JavaScript

Python

Scala

SQL

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

1

Weitere Informationen zu Einschränkungen bei der gemeinsamen Nutzung von Java-UDFs finden Sie unter Allgemeine Einschränkungen.

2

Weitere Informationen zu Einschränkungen bei der gemeinsamen Nutzung von Python-UDFs finden Sie unter Allgemeine Einschränkungen.

3

Weitere Informationen zu Einschränkungen bei der gemeinsamen Nutzung von Scala-UDFs finden Sie unter Scala-UDF-Einschränkungen.

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:

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.