CREATE FUNCTION

Erstellt eine neue UDF (benutzerdefinierte Funktion). Die Funktion kann entweder skalare Ergebnisse (als UDF) oder tabellarische Ergebnisse (als UDTF) zurückgeben.

Wenn Sie eine UDF erstellen, geben Sie einen Handler an, dessen Code in einer der unterstützten Sprachen geschrieben ist. Je nach Sprache des Handlers können Sie entweder den Quellcode des Handlers in die CREATE FUNCTION-Anweisung einbinden oder den Speicherort des Handlers von CREATE FUNCTION aus referenzieren, wo der Handler vorkompiliert oder Quellcode in einem Stagingbereich ist.

Die folgende Tabelle listet die unterstützten Sprachen auf und gibt an, ob der Code inline mit CREATE FUNCTION oder in einer Datei in einem Stagingbereich bereitgestellt werden kann. Weitere Informationen dazu finden Sie unter Speichern von Handler-Code inline oder in einem Stagingbereich.

Sprache

Speicherort des Handlers

Java

Inline oder Staging

JavaScript

Inline

Python

Inline oder Staging

Scala

Inline oder Staging

SQL

Inline

Siehe auch:

ALTER FUNCTION, DROP FUNCTION, SHOW USER FUNCTIONS, DESCRIBE FUNCTION

Syntax

Die Syntax für CREATE FUNCTION variiert je nachdem, welche Programmiersprache Sie für den UDF-Handler verwenden.

Java-Handler

Verwenden Sie die folgende Syntax, wenn der Quellcode inline ist:

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  LANGUAGE JAVA
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ RUNTIME_VERSION = <java_jdk_version> ]
  [ COMMENT = '<string_literal>' ]
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] ) ]
  [ PACKAGES = ( '<package_name_and_version>' [ , ... ] ) ]
  HANDLER = '<path_to_method>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ TARGET_PATH = '<stage_path_and_file_name_to_write>' ]
  AS '<function_definition>'
Copy

Verwenden Sie die folgende Syntax, wenn der Handler-Code in einem Stagingbereich referenziert wird (in einer JAR-Datei):

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  LANGUAGE JAVA
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ RUNTIME_VERSION = <java_jdk_version> ]
  [ COMMENT = '<string_literal>' ]
  IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] )
  HANDLER = '<path_to_method>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
Copy

JavaScript-Handler

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  LANGUAGE JAVASCRIPT
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ COMMENT = '<string_literal>' ]
  AS '<function_definition>'
Copy

Python-Handler

Verwenden Sie die folgende Syntax, wenn der Quellcode inline ist:

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  LANGUAGE PYTHON
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  RUNTIME_VERSION = <python_version>
  [ COMMENT = '<string_literal>' ]
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] ) ]
  [ PACKAGES = ( '<package_name>[==<version>]' [ , ... ] ) ]
  HANDLER = '<function_name>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  AS '<function_definition>'
Copy

Verwenden Sie die folgende Syntax, wenn der Handler-Code in einem Stagingbereich referenziert wird (in einem Modul):

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  LANGUAGE PYTHON
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  RUNTIME_VERSION = <python_version>
  [ COMMENT = '<string_literal>' ]
  IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] )
  [ PACKAGES = ( '<package_name>[==<version>]' [ , ... ] ) ]
  HANDLER = '<module_file_name>.<function_name>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
Copy

Scala-Handler

Verwenden Sie die folgende Syntax, wenn der Quellcode inline ist:

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  LANGUAGE SCALA
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ RUNTIME_VERSION = <scala_version> ]
  [ COMMENT = '<string_literal>' ]
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] ) ]
  [ PACKAGES = ( '<package_name_and_version>' [ , ... ] ) ]
  HANDLER = '<path_to_method>'
  [ TARGET_PATH = '<stage_path_and_file_name_to_write>' ]
  AS '<function_definition>'
Copy

Verwenden Sie die folgende Syntax, wenn der Handler-Code in einem Stagingbereich referenziert wird (in einer JAR-Datei):

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION [ IF NOT EXISTS ] <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  LANGUAGE SCALA
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ RUNTIME_VERSION = <scala_version> ]
  [ COMMENT = '<string_literal>' ]
  IMPORTS = ( '<stage_path_and_file_name_to_read>' [ , ... ] )
  HANDLER = '<path_to_method>'
Copy

SQL-Handler

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY } ] [ SECURE ] FUNCTION <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( <col_name> <col_data_type> [ , ... ] ) }
  [ [ NOT ] NULL ]
  [ { VOLATILE | IMMUTABLE } ]
  [ MEMOIZABLE ]
  [ COMMENT = '<string_literal>' ]
  AS '<function_definition>'
Copy

Erforderliche Parameter

Alle Sprachen

name ( [ arg_name arg_data_type [ DEFAULT default_value ] ] [ , ... ] )

Gibt den Bezeichner (name), alle Eingabeargumente und die Standardwerte aller optionalen Argumente der UDF an.

RETURNS ...

Gibt die von der UDF zurückgegebenen Ergebnisse an, die den UDF-Typ bestimmen:

  • result_data_type: Erstellt eine skalare UDF, die einen Einzelwert mit dem angegebenen Datentyp zurückgibt.

    Bemerkung

    Für UDF-Handler, die in Java, Python oder Scala geschrieben sind, muss der Wert von result_data_type in der Spalte SQL Data Type der folgenden Tabelle der jeweiligen Handler-Sprache enthalten sein:

  • TABLE ( col_name col_data_type , ... ): Erstellt eine tabellarische UDF, die Tabellen mit den angegebenen Tabellenspalten und Spaltentypen zurückgibt.

    Bemerkung

    Bei Scala-UDFs wird der Rückgabetyp TABLE nicht unterstützt.

AS function_definition

Definiert den Handler-Code, der beim Aufruf der UDF ausgeführt wird. Der Wert von function_definition muss der Quellcode in einer der Sprachen sein, die von Handlern unterstützt werden. Folgende Sprachen werden für den Code unterstützt:

Weitere Details dazu finden Sie unter Nutzungshinweise (unter diesem Thema).

Bemerkung

Die AS-Klausel ist nicht erforderlich, wenn mit der IMPORTS-Klausel auf den UDF-Handler-Code im Stagingbereich verwiesen wird.

Java

LANGUAGE JAVA

Gibt an, dass der Code in der Sprache Java vorliegt.

RUNTIME_VERSION = java_jdk_version

Gibt die zu verwendende Java JDK-Laufzeitversion an. Folgende Java-Versionen werden unterstützt:

  • 11.x

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

Wenn RUNTIME_VERSION nicht festgelegt ist, wird Java JDK 11 verwendet.

IMPORTS = ( 'stage_path_and_file_name_to_read' [ , ... ] )

Der Speicherort (Stagingbereich), der Pfad und der Name der zu importierenden Datei(en).

Eine Datei kann eine JAR-Datei oder ein anderer Typ von Datei sein.

Wenn die Datei eine JAR-Datei ist, kann sie eine oder mehrere .class-Dateien und keine oder mehrere Ressourcendateien enthalten.

JNI (Java Native Interface) wird nicht unterstützt. Snowflake verbietet das Laden von Bibliotheken, die nativen Code (im Gegensatz zu Java-Bytecode) enthalten.

Java-UDFs können auch Nicht-JAR-Dateien lesen. Ein Beispiel finden Sie unter Lesen einer in IMPORTS statisch spezifizierten Datei.

Wenn Sie vorhaben, eine Datei (JAR-Datei oder eine andere Datei) in einen Stagingbereich zu kopieren, empfiehlt Snowflake die Verwendung eines benannten internen Stagingbereichs, da der PUT-Befehl das Kopieren von Dateien in benannte interne Stagingbereiche unterstützt und der PUT-Befehl normalerweise die einfachste Möglichkeit ist, eine JAR-Datei in einen Stagingbereich zu verschieben.

Externe Stagingbereiche sind erlaubt, werden aber von PUT nicht unterstützt.

Jede Datei in der IMPORTS-Klausel muss einen eindeutigen Namen haben, auch wenn sich die Dateien in verschiedenen Unterverzeichnissen oder verschiedenen Stagingbereichen befinden.

Wenn sowohl die IMPORTS- als auch die TARGET_PATH-Klausel vorhanden ist, muss sich der Dateiname in der TARGET_PATH-Klausel von jedem Dateinamen in der IMPORTS-Klausel unterscheiden, auch wenn sich die Dateien in verschiedenen Unterverzeichnissen oder verschiedenen Stagingbereichen befinden.

Snowflake gibt einen Fehler zurück, wenn TARGET_PATH mit einer vorhandenen Datei übereinstimmt. Sie können TARGET_PATH nicht verwenden, um eine vorhandene Datei zu überschreiben.

Bei einer UDF, deren Handler sich in einem Stagingbereich befindet, ist die IMPORTS-Klausel erforderlich, da sie den Speicherort der JAR-Datei angibt, die die UDF enthält.

Bei einer UDF, deren Handler-Code inline bereitgestellt wird, wird die IMPORTS-Klausel nur dann benötigt, wenn die Inline-UDF auf andere Dateien, wie z. B. Bibliotheken oder Textdateien, zugreifen muss.

Bei Snowflake-Systempaketen, wie dem Snowpark-Paket, können Sie das Paket mit der PACKAGES-Klausel angeben, anstatt seine JAR-Datei mit IMPORTS zu spezifizieren. Wenn Sie dies tun, muss die JAR-Paketdatei nicht in einem IMPORTS-Wert enthalten sein.

Inline-Java

AS function_definition

Inline-Java-UDFs erfordern eine Funktionsdefinition.

HANDLER = handler_name

Der Name der Handler-Methode oder -Klasse.

  • Wenn der Handler für eine skalare UDF ist, die einen nicht tabellarischen Wert zurückgibt, muss der Wert von HANDLER ein Methodenname in der folgenden Form sein: MyClass.myMethod.

  • Wenn der Handler für eine tabellarische UDF ist, muss der Wert von HANDLER der Name einer Handler-Klasse sein.

JavaScript

LANGUAGE JAVASCRIPT

Gibt an, dass der Code in der Sprache JavaScript vorliegt.

Python

LANGUAGE PYTHON

Gibt an, dass der Code in der Sprache Python vorliegt.

RUNTIME_VERSION = python_version

Gibt die zu verwendende Python-Version an. Folgende Versionen von Python werden unterstützt:

  • 3.8

  • 3.9

  • 3.10

  • 3.11

IMPORTS = ( 'stage_path_and_file_name_to_read' [ , ... ] )

Der Speicherort (Stagingbereich), der Pfad und der Name der zu importierenden Datei(en).

Eine Datei kann eine .py-Datei oder ein anderer Typ von Datei sein.

Python-UDFs können auch Nicht-Python-Dateien lesen, z. B. Textdateien. Ein Beispiel dazu finden Sie unter Lesen einer Datei.

Wenn Sie vorhaben, eine Datei in einen Stagingbereich zu kopieren, empfiehlt Snowflake die Verwendung eines benannten internen Stagingbereichs, denn der PUT-Befehl unterstützt das Kopieren von Dateien in benannte interne Stagingbereiche und der PUT-Befehl ist normalerweise die einfachste Möglichkeit, eine Datei in einen Stagingbereich zu verschieben.

Externe Stagingbereiche sind erlaubt, werden aber von PUT nicht unterstützt.

Jede Datei in der IMPORTS-Klausel muss einen eindeutigen Namen haben, auch wenn sich die Dateien in verschiedenen Unterverzeichnissen oder verschiedenen Stagingbereichen befinden.

Wenn der Handler-Code in einem Stagingbereich gespeichert ist, müssen Sie die IMPORTS-Klausel verwenden, um den Speicherort des Handler-Codes anzugeben.

Für eine Inline-Python-UDF wird die IMPORTS-Klausel nur dann benötigt, wenn der UDF-Handler auf andere Dateien, wie Pakete oder Textdateien, zugreifen muss.

Für Pakete, die wie numpy im Snowflake-System integriert sind, müssen Sie nur die PACKAGES-Klausel angeben und können die Angabe der Quelle des Pakets mit IMPORTS-Wert weglassen.

HANDLER = handler_name

Der Name der Handler-Funktion oder -Klasse.

  • Wenn der Handler für eine skalare UDF ist, die einen nicht tabellarischen Wert zurückgibt, muss der Wert von HANDLER ein Funktionsname sein. Wenn der Handler-Code inline in der CREATE FUNCTION-Anweisung angegeben wird, können Sie den Funktionsnamen allein verwenden. Wenn der Handler-Code in einem Stagingbereich referenziert wird, muss dieser Wert mit dem Modulnamen in folgender Form qualifiziert werden: my_module.my_function.

  • Wenn der Handler für eine tabellarische UDF ist, muss der Wert von HANDLER der Name einer Handler-Klasse sein.

Scala

LANGUAGE SCALA

Gibt an, dass der Code in der Sprache Scala ist.

RUNTIME_VERSION = scala_version

Gibt die zu verwendende Scala-Laufzeitversion an. Die unterstützten Versionen von Scala sind:

  • 2.12

Wenn RUNTIME_VERSION nicht festgelegt ist, wird Scala 2.12 verwendet.

IMPORTS = ( 'stage_path_and_file_name_to_read' [ , ... ] )

Der Speicherort (Stagingbereich), der Pfad und der Name der zu importierenden Datei(en), wie eine JAR-Datei oder ein anderer Typ von Datei.

  • Die JAR-Datei kann Bibliotheken mit Handler-Abhängigkeiten enthalten. Sie kann eine oder mehrere .class-Dateien und keine oder mehrere Ressourcendateien enthalten.

    JNI (Java Native Interface) wird nicht unterstützt. Snowflake verbietet das Laden von Bibliotheken, die nativen Code (im Gegensatz zu Java-Bytecode) enthalten.

  • Eine Nicht-JAR-Datei kann eine Datei sein, die von Handler-Code gelesen wird. Ein Beispiel dazu finden Sie unter Lesen einer in IMPORTS statisch spezifizierten Datei.

Wenn Sie vorhaben, eine Datei in einen Stagingbereich zu kopieren, empfiehlt Snowflake die Verwendung eines benannten internen Stagingbereichs, denn der PUT-Befehl unterstützt das Kopieren von Dateien in benannte interne Stagingbereiche und der PUT-Befehl ist normalerweise die einfachste Möglichkeit, eine JAR-Datei in einen Stagingbereich zu verschieben. Externe Stagingbereiche sind erlaubt, werden aber von PUT nicht unterstützt.

Jede Datei in der IMPORTS-Klausel muss einen eindeutigen Namen haben, auch wenn sich die Dateien in verschiedenen Unterverzeichnissen des Stagingbereichs oder in verschiedenen Stagingbereichen befinden.

Wenn sowohl die IMPORTS- als auch die TARGET_PATH-Klausel vorhanden ist, muss sich der Dateiname in der TARGET_PATH-Klausel von jedem in der IMPORTS-Klausel aufgeführten Dateinamen unterscheiden, auch wenn sich die Dateien in verschiedenen Unterverzeichnissen des Stagingbereichs oder in verschiedenen Stagingbereichen befinden.

Bei einer UDF, deren Handler sich in einem Stagingbereich befindet, ist die IMPORTS-Klausel erforderlich, da sie den Speicherort der JAR-Datei angibt, die die UDF enthält.

Bei einer UDF, deren Handler-Code inline bereitgestellt wird, wird die IMPORTS-Klausel nur dann benötigt, wenn die Inline-UDF auf andere Dateien, wie z. B. Bibliotheken oder Textdateien, zugreifen muss.

Bei Snowflake-Systempaketen, wie dem Snowpark-Paket, können Sie das Paket mit der PACKAGES-Klausel angeben, anstatt seine JAR-Datei mit IMPORTS zu spezifizieren. Wenn Sie dies tun, muss die JAR-Paketdatei nicht in einem IMPORTS-Wert enthalten sein.

Inline-Scala

AS function_definition

UDFs, deren Scala-Handler-Code inline ist, erfordern eine Funktionsdefinition.

HANDLER = handler_name

Der Name der Handler-Methode oder -Klasse.

  • Wenn der Handler für eine skalare UDF ist, die einen nicht tabellarischen Wert zurückgibt, muss der Wert von HANDLER ein Methodenname in der folgenden Form sein: MyClass.myMethod.

Optionale Parameter

Alle Sprachen

SECURE

Gibt an, dass die Funktion sicher ist. Weitere Informationen zu sicheren Funktionen finden Sie unter Schutz sensibler Informationen mit sicheren UDFs und gespeicherten Prozeduren.

{ TEMP | TEMPORARY }

Legt fest, dass die Funktion nur für die Dauer der Sitzung bestehen bleibt, in der Sie sie erstellt haben. Eine temporäre Funktion wird am Ende der Sitzung gelöscht.

Standard: Kein Wert. Wenn eine Funktion nicht als TEMPORARY deklariert ist, ist die Funktion permanent.

Sie können keine temporären benutzerdefinierten Funktionen erstellen, die denselben Namen haben wie eine Funktion, die bereits im Schema vorhanden ist.

[ [ NOT ] NULL ]

Gibt an, ob die Funktion auch NULL-Werte oder nur NON-NULL-Werte zurückgeben kann. Der Standardwert ist NULL (d. h. die Funktion kann NULL zurückgeben).

Bemerkung

Derzeit wird die NOT NULL-Klausel bei SQL-UDFs nicht erzwungen. Als NOT NULL deklarierte SQL-UDFs können NULL-Werte zurückgeben. Snowflake empfiehlt, NOT NULL nicht für SQL-UDFs zu verwenden, es sei denn, der Code in der Funktion wurde geschrieben, um sicherzustellen, dass niemals NULL-Werte zurückgegeben werden.

CALLED ON NULL INPUT oder . { RETURNS NULL ON NULL INPUT | STRICT }

Gibt das Verhalten der UDF an, wenn sie mit Null-Eingaben aufgerufen wird. Im Gegensatz zu systemdefinierten Funktionen, die immer Null zurückgeben, wenn eine Eingabe Null ist, können UDFs Null-Eingaben verarbeiten und Nicht-Null-Werte zurückgeben, auch wenn eine Eingabe Null ist:

  • CALLED ON NULL INPUT ruft immer die UDF mit Null-Eingaben auf. Es liegt an der UDF, mit solchen Werten angemessen umzugehen.

  • RETURNS NULL ON NULL INPUT (oder sein Synonym STRICT) ruft UDF nicht auf, wenn eine Eingabe Null ist. Stattdessen wird immer ein Null-Wert für diese Zeile zurückgegeben. Beachten Sie, dass die UDF bei Nicht-Null-Eingaben immer noch Null zurückgeben kann.

Bemerkung

RETURNS NULL ON NULL INPUT (STRICT) wird für SQL-UDFs nicht unterstützt. SQL-UDFs nutzen CALLED ON NULL INPUT effizient. Ihre SQL-UDFs muss Null-Eingabewerte behandeln.

Standard: CALLED ON NULL INPUT

{ VOLATILE | IMMUTABLE }

Gibt das Verhalten der UDF bei der Rückgabe des Ergebnisses an:

  • VOLATILE: Die UDF kann für verschiedene Zeilen unterschiedliche Werte zurückgeben, auch bei gleicher Eingabe (z. B. aufgrund von Nichtdeterminismus und Statefullness).

  • IMMUTABLE: UDF geht davon aus, dass die Funktion, wenn sie mit den gleichen Eingabewerten aufgerufen wird, immer das gleiche Ergebnis liefert. Diese Garantie wird nicht geprüft. Die Angabe von IMMUTABLE für eine UDF, die unterschiedliche Werte für dieselbe Eingabe zurückgibt, führt zu einem undefinierten Verhalten.

Standard: VOLATILE

COMMENT = 'string_literal'

Gibt einen Kommentar für die UDF an, der in der Spalte DESCRIPTION in der Ausgabe SHOW FUNCTIONS und SHOW USER FUNCTIONS angezeigt wird.

Standard: user-defined function

COPY GRANTS

Gibt an, dass die Zugriffsrechte der ursprünglichen Funktion beibehalten werden sollen, wenn eine neue Funktion mit CREATE OR REPLACE FUNCTION erstellt wird.

Der Parameter kopiert alle Berechtigungen mit Ausnahme von OWNERSHIP aus der bestehenden Funktion in die neue Funktion. Die neue Funktion erbt keine der zukünftigen Berechtigungszuweisungen, die für den Objekttyp im Schema definiert sind. Standardmäßig ist die Rolle, die die Anweisung CREATE FUNCTION ausführt, Eigentümer der neuen Funktion.

Hinweis:

  • Beim Data Sharing wird bei Freigabe der vorhandenen Funktion für ein anderes Konto auch die Ersetzungsfunktion freigegeben.

  • Die SHOW GRANTS-Ausgabe für die Ersetzungsfunktion listet den Berechtigungsempfänger für die kopierten Berechtigungen als Rolle auf, die die CREATE FUNCTION-Anweisung ausgeführt hat, und mit dem aktuellen Zeitstempel für die Ausführung der Anweisung.

  • Die Operation zum Kopieren von Berechtigungen erfolgt atomar im Befehl CREATE FUNCTION (d. h. innerhalb derselben Transaktion).

Java

PACKAGES = ( 'package_name_and_version' [ , ... ] )

Der Name und die Versionsnummer der Snowflake-Systempakete, die als Abhängigkeiten benötigt werden. Der Wert muss die Form package_name:version_number haben, wobei der Paketname package_name der Bezeichner snowflake_domain:package ist. Beachten Sie, dass Sie latest als Versionsnummer angeben können, sodass Snowflake die neueste auf dem System verfügbare Version verwendet.

Beispiel:

-- Use version 1.2.0 of the Snowpark package.
PACKAGES=('com.snowflake:snowpark:1.2.0')

-- Use the latest version of the Snowpark package.
PACKAGES=('com.snowflake:snowpark:latest')
Copy

Sie können die Liste der unterstützten Systempakete ermitteln, indem Sie in Snowflake den folgenden SQL-Befehl ausführen:

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'java';
Copy

Für eine Abhängigkeit, die Sie mit PACKAGES angeben, müssen Sie die zugehörige JAR-Datei nicht zusätzlich in einer IMPORTS-Klausel angeben.

Inline-Java

TARGET_PATH = stage_path_and_file_name_to_write

Die TARGET_PATH-Klausel gibt den Speicherort an, in den Snowflake den kompilierten Code (JAR-Datei) nach der Kompilierung des in function_definition angegebenen Quellcodes schreiben soll.

Wenn diese Klausel enthalten ist, sollte der Benutzer die JAR-Datei manuell entfernen, wenn sie nicht mehr benötigt wird (typischerweise, wenn die Java-UDF gelöscht wird).

Wenn diese Klausel weggelassen wird, kompiliert Snowflake den Quellcode jedes Mal neu, wenn der Code benötigt wird. Die JAR-Datei wird nicht dauerhaft gespeichert, und der Benutzer muss die JAR-Datei nicht bereinigen.

Snowflake gibt einen Fehler zurück, wenn TARGET_PATH mit einer vorhandenen Datei übereinstimmt. Sie können TARGET_PATH nicht verwenden, um eine vorhandene Datei zu überschreiben.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

Die Namen der Integrationen für den externen Zugriff, die benötigt werden, damit der Handler-Code dieser Funktion auf externe Netzwerke zugreifen kann.

Eine Integration für den externen Zugriff enthält Netzwerkregeln und Geheimnisse, die die externen Standorte und Anmeldeinformationen (falls vorhanden) angeben, die für den Handler-Code benötigt werden, um Anfragen an ein externes Netzwerk, wie z. B. ein externes REST API, zu stellen.

Weitere Informationen dazu finden Sie unter Übersicht über externen Netzwerkzugriff.

SECRETS = ( 'secret_variable_name' = secret_name [ , ...  ] )

Weist die Namen von Geheimnissen Variablen zu, sodass Sie die Variablen verwenden können, um auf die Geheimnisse zu verweisen, wenn Sie Informationen aus Geheimnissen im Handler-Code abrufen.

Der Wert dieses Parameters ist eine durch Kommas getrennte Liste von Zuweisungsausdrücken mit den folgenden Bestandteilen:

  • secret_name als Name eines Geheimnisses, das im Parameterwert einer Integration für externen Zugriff ALLOWED_AUTHENTICATION_SECRETS angegeben ist. Der Name dieser Integration für externen Zugriff muss wiederum als Wert des EXTERNAL_ACCESS_INTEGRATIONS-Parameters dieses CREATE FUNCTION-Aufrufs angegeben werden.

    Sie erhalten einen Fehler, wenn Sie einen SECRETS-Wert angeben, dessen Geheimnis nicht auch in einer durch den EXTERNAL_ACCESS_INTEGRATIONS-Parameter angegebenen Integration enthalten ist.

  • 'secret_variable_name' als die Variable, die im Handler-Code verwendet wird, um Informationen aus dem Geheimnis abzurufen.

Weitere Informationen dazu, einschließlich eines Beispiels, finden Sie unter Verwendung der Integration für den externen Zugriff in einer Funktion oder Prozedur.

Python

PACKAGES = ( 'package_name_and_version' [ , ... ] )

Name und Versionsnummer der Pakete, die als Abhängigkeiten benötigt werden. Der Wert muss die Form package_name==version_number haben. Wenn Sie die Versionsnummer weglassen, verwendet Snowflake die aktuell im System verfügbare Paketversion.

Beispiel:

-- Use version 1.2.2 of the NumPy package.
PACKAGES=('numpy==1.2.2')

-- Use the latest version of the NumPy package.
PACKAGES=('numpy')
Copy

Sie können die Liste der unterstützten Systempakete ermitteln, indem Sie in Snowflake den folgenden SQL-Befehl ausführen:

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'python';
Copy

Weitere Informationen zu den enthaltenen Paketen finden Sie unter Verwenden von Drittanbieter-Paketen.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

Die Namen der Integrationen für den externen Zugriff, die benötigt werden, damit der Handler-Code dieser Funktion auf externe Netzwerke zugreifen kann.

Eine Integration für den externen Zugriff enthält Netzwerkregeln und Geheimnisse, die die externen Standorte und Anmeldeinformationen (falls vorhanden) angeben, die für den Handler-Code benötigt werden, um Anfragen an ein externes Netzwerk, wie z. B. ein externes REST API, zu stellen.

Weitere Informationen dazu finden Sie unter Übersicht über externen Netzwerkzugriff.

SECRETS = ( 'secret_variable_name' = secret_name [ , ...  ])

Weist die Namen von Geheimnissen Variablen zu, sodass Sie die Variablen verwenden können, um auf die Geheimnisse zu verweisen, wenn Sie Informationen aus Geheimnissen im Handler-Code abrufen.

Der Wert dieses Parameters ist eine durch Kommas getrennte Liste von Zuweisungsausdrücken mit den folgenden Bestandteilen:

  • secret_name als Name eines Geheimnisses, das im Parameterwert einer Integration für externen Zugriff ALLOWED_AUTHENTICATION_SECRETS angegeben ist. Der Name dieser Integration für externen Zugriff muss wiederum als Wert des EXTERNAL_ACCESS_INTEGRATIONS-Parameters dieses CREATE FUNCTION-Aufrufs angegeben werden.

    Sie erhalten einen Fehler, wenn Sie einen SECRETS-Wert angeben, dessen Geheimnis nicht auch in einer durch den EXTERNAL_ACCESS_INTEGRATIONS-Parameter angegebenen Integration enthalten ist.

  • 'secret_variable_name' als die Variable, die im Handler-Code verwendet wird, um Informationen aus dem Geheimnis abzurufen.

Weitere Informationen dazu, einschließlich eines Beispiels, finden Sie unter Verwendung der Integration für den externen Zugriff in einer Funktion oder Prozedur.

SQL

MEMOIZABLE

Gibt an, dass die Funktion memoisierbar ist.

Weitere Details dazu finden Sie unter Memoisierbare UDFs.

Scala

PACKAGES = ( 'package_name_and_version' [ , ... ] )

Der Name und die Versionsnummer der Snowflake-Systempakete, die als Abhängigkeiten benötigt werden. Der Wert muss die Form package_name:version_number haben, wobei der Paketname package_name der Bezeichner snowflake_domain:package ist. Beachten Sie, dass Sie latest als Versionsnummer angeben können, sodass Snowflake die neueste auf dem System verfügbare Version verwendet.

Beispiel:

-- Use version 1.7.0 of the Snowpark package.
PACKAGES=('com.snowflake:snowpark:1.7.0')

-- Use the latest version of the Snowpark package.
PACKAGES=('com.snowflake:snowpark:latest')
Copy

Sie können die Liste der unterstützten Systempakete ermitteln, indem Sie in Snowflake den folgenden SQL-Befehl ausführen:

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'scala';
Copy

Für eine Abhängigkeit, die Sie mit PACKAGES angeben, müssen Sie die zugehörige JAR-Datei nicht zusätzlich in einer IMPORTS-Klausel angeben.

Inline-Scala

TARGET_PATH = stage_path_and_file_name_to_write

Die TARGET_PATH-Klausel gibt den Speicherort an, in den Snowflake den kompilierten Code (JAR-Datei) nach der Kompilierung des in function_definition angegebenen Quellcodes schreiben soll.

Wenn diese Klausel enthalten ist, sollten Sie die JAR-Datei manuell entfernen, wenn sie nicht mehr benötigt wird (typischerweise, wenn die UDF gelöscht wird).

Wenn diese Klausel weggelassen wird, kompiliert Snowflake den Quellcode jedes Mal neu, wenn der Code benötigt wird. Die JAR-Datei wird nicht permanent gespeichert, und Sie müssen die JAR-Datei nicht bereinigen.

Snowflake gibt einen Fehler zurück, wenn TARGET_PATH mit einer vorhandenen Datei übereinstimmt. Sie können TARGET_PATH nicht verwenden, um eine vorhandene Datei zu überschreiben.

Anforderungen an die Zugriffssteuerung

Eine Rolle, die zur Ausführung dieses SQL-Befehls verwendet wird, muss mindestens die folgenden Berechtigungen haben:

Berechtigung

Objekt

Anmerkungen

CREATE FUNCTION

Schema

USAGE

Funktion

Wenn Sie einer Rolle die Berechtigung USAGE für die neu erstellte Funktion erteilen, können Benutzer mit dieser Rolle die Funktion an anderer Stelle in Snowflake aufrufen (z. B. Eigentümerrolle einer Maskierungsrichtlinie für externe Tokenisierung).

USAGE

Integration für externen Zugriff

Erforderlich bei Integrationen, falls vorhanden, die mit dem Parameter EXTERNAL_ACCESS_INTEGRATIONS angegeben werden. Weitere Informationen dazu finden Sie unter CREATE EXTERNAL ACCESS INTEGRATION.

READ

Geheimnis

Erforderlich bei Geheimnissen, falls vorhanden, die mit dem Parameter SECRETS angegeben werden. Weitere Informationen dazu finden Sie unter Erstellen eines Geheimnisses zur Darstellung von Anmeldeinformationen und Verwendung der Integration für den externen Zugriff in einer Funktion oder Prozedur.

USAGE

Schema

Erforderlich bei Schemas mit Geheimnissen, falls vorhanden, die mit dem Parameter SECRETS angegeben werden. Weitere Informationen dazu finden Sie unter Erstellen eines Geheimnisses zur Darstellung von Anmeldeinformationen und Verwendung der Integration für den externen Zugriff in einer Funktion oder Prozedur.

Beachten Sie, dass für die Bearbeitung eines Objekts in einem Schema auch die Berechtigung USAGE für die übergeordnete Datenbank und das Schema erforderlich ist.

Eine Anleitung zum Erstellen einer kundenspezifischen Rolle mit einer bestimmten Gruppe von Berechtigungen finden Sie unter Erstellen von kundenspezifischen Rollen.

Allgemeine Informationen zu Rollen und Berechtigungen zur Durchführung von SQL-Aktionen auf sicherungsfähigen Objekten finden Sie unter Übersicht zur Zugriffssteuerung.

Nutzungshinweise

Alle Sprachen

  • function_definition hat Größenbeschränkungen. Die maximal zulässige Größe kann sich ändern.

  • Die Trennzeichen um function_definition können einfache Anführungszeichen oder doppelte Dollarzeichen sein.

    Eine Verwendung von $$ als Trennzeichen vereinfacht das Schreiben von Funktionen, die einfache Anführungszeichen enthalten.

    Wenn als Trennzeichen für den Textköper der Funktion das einfache Anführungszeichen verwendet wird, müssen alle Anführungszeichen innerhalb von function_definition (z. B. Zeichenfolgenliterale) mit einfachen Anführungszeichen als Escape-Zeichen versehen werden.

  • Wenn Sie eine UDF in einer Maskierungsrichtlinie verwenden, müssen Sie sicherstellen, dass die Datentypen von Spalte, UDF und Maskierungsrichtlinie übereinstimmen. Weitere Informationen dazu finden Sie unter Benutzerdefinierte Funktionen in einer Maskierungsrichtlinie.

  • Metadaten:

    Achtung

    Kunden müssen sicherstellen, dass bei der Nutzung des Snowflake-Dienstes keine personenbezogenen Daten (außer für ein Objekt „Benutzer“), sensible Daten, exportkontrollierte Daten oder andere regulierte Daten als Metadaten eingegeben werden. Weitere Informationen dazu finden Sie unter Metadatenfelder in Snowflake.

  • CREATE OR REPLACE <Objekt>-Anweisungen sind atomar. Das heißt, wenn ein Objekt ersetzt wird, erfolgt das Löschen des alten Objekts und das Erstellen des neuen Objekts in einer einzigen Transaktion.

Java

  • In Java lassen primitive Datentypen keine NULL-Werte zu, sodass die Übergabe eines NULL-Wertes für ein Argument eines solchen Typs zu einem Fehler führt.

  • In der HANDLER-Klausel wird beim Methodennamen zwischen Groß- und Kleinschreibung unterschieden.

  • In den Klauseln IMPORTS und TARGET_PATH:

    • Bei Paket-, Klassen- und Dateinamen wird Groß-/Kleinschreibung unterschieden.

    • Bei Stagingbereichsnamen wird Groß-/Kleinschreibung nicht unterschieden.

  • Sie können die PACKAGES-Klausel verwenden, um Paketname und Versionsnummer für systemdefinierte Snowflake-Abhängigkeiten, wie z. B. die von Snowpark, anzugeben. Für andere Abhängigkeiten geben Sie die JAR-Abhängigkeitsdateien mit der Klausel IMPORTS an.

  • Snowflake validiert Folgendes:

    • Die im HANDLER der CREATE FUNCTION-Anweisung angegebene JAR-Datei existiert und enthält die angegebene Klasse und Methode.

    • Die in der UDF-Deklaration angegebenen Eingangs- und Ausgangstypen sind mit den Eingangs- und Ausgangstypen der Java-Methode kompatibel.

    Die Validierung kann zur Erstellungszeit oder zur Ausführungszeit erfolgen.

    • Wenn der Benutzer zum Zeitpunkt der Ausführung der CREATE FUNCTION-Anweisung mit einem aktiven Snowflake-Warehouse verbunden ist, wird die UDF zum Erstellungszeitpunkt validiert.

    • Andernfalls wird die UDF erstellt, aber nicht sofort validiert, und Snowflake gibt die folgende Meldung zurück: Function <Name> created successfully, but could not be validated since there is no active warehouse.

JavaScript

  • Snowflake validiert JavaScript-Code nicht zum Zeitpunkt der UDF-Erstellung (d. h. die Erstellung der UDF ist erfolgreich, unabhängig davon, ob der Code gültig ist). Wenn der Code nicht gültig ist, werden bei Aufruf der UDF zur Abfragezeit Fehler zurückgegeben.

Python

  • In der HANDLER-Klausel wird beim Namen der Handler-Funktion zwischen Groß- und Kleinschreibung unterschieden.

  • Für die IMPORTS-Klausel gilt:

    • Bei Dateinamen wird Groß-/Kleinschreibung unterschieden.

    • Bei Stagingbereichsnamen wird Groß-/Kleinschreibung nicht unterschieden.

  • Sie können die PACKAGES-Klausel verwenden, um Paketname und Versionsnummer für systemdefinierte Snowflake-Abhängigkeiten, wie z. B. der von Snowpark, anzugeben. Für andere Abhängigkeiten geben Sie die Abhängigkeitsdateien mit der IMPORTS-Klausel an.

  • Snowflake validiert Folgendes:

    • Die im HANDLER-Code der CREATE FUNCTION-Anweisung angegebene Funktion oder Klasse ist vorhanden.

    • Die in der UDF-Deklaration angegebenen Eingangs- und Ausgangstypen sind mit den Eingangs- und Ausgangstypen des Handlers kompatibel.

Scala

  • In der HANDLER-Klausel wird beim Methodennamen zwischen Groß- und Kleinschreibung unterschieden.

  • In den Klauseln IMPORTS und TARGET_PATH:

    • Bei Paket-, Klassen- und Dateinamen wird Groß-/Kleinschreibung unterschieden.

    • Bei Stagingbereichsnamen wird Groß-/Kleinschreibung nicht unterschieden.

  • Sie können die PACKAGES-Klausel verwenden, um Paketname und Versionsnummer für systemdefinierte Snowflake-Abhängigkeiten, wie z. B. die von Snowpark, anzugeben. Für andere Abhängigkeiten geben Sie die JAR-Abhängigkeitsdateien mit der Klausel IMPORTS an.

  • Snowflake validiert Folgendes:

    • Die im HANDLER der CREATE FUNCTION-Anweisung angegebene JAR-Datei existiert und enthält die angegebene Klasse und Methode.

    • Die in der UDF-Deklaration angegebenen Eingangs- und Ausgangstypen sind mit den Eingangs- und Ausgangstypen der Scala-Methode kompatibel.

    Die Validierung kann zur Erstellungszeit oder zur Ausführungszeit erfolgen.

    • Wenn der Benutzer zum Zeitpunkt der Ausführung der CREATE FUNCTION-Anweisung mit einem aktiven Snowflake-Warehouse verbunden ist, wird die UDF zum Erstellungszeitpunkt validiert.

    • Andernfalls wird die UDF erstellt, aber nicht sofort validiert, und Snowflake gibt die folgende Meldung zurück: Function <Name> created successfully, but could not be validated since there is no active warehouse.

SQL

  • Derzeit wird die NOT NULL-Klausel bei SQL-UDFs nicht erzwungen.

Beispiele

Java

Hier ist ein grundlegendes Beispiel für eine CREATE FUNCTION-Anweisung mit einem Inline-Handler:

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

Hier ist ein einfaches Beispiel für CREATE FUNCTION mit einem Verweis auf einen Staging-Handler:

create function my_decrement_udf(i numeric(9, 0))
    returns numeric
    language java
    imports = ('@~/my_decrement_udf_package_dir/my_decrement_udf_jar.jar')
    handler = 'my_decrement_udf_package.my_decrement_udf_class.my_decrement_udf_method'
    ;
Copy

Weitere Beispiele für Java-UDFs finden Sie unter Beispiele.

JavaScript

Erstellen Sie eine JavaScript-UDF mit dem Namen js_factorial:

CREATE OR REPLACE FUNCTION js_factorial(d double)
  RETURNS double
  LANGUAGE JAVASCRIPT
  STRICT
  AS '
  if (D <= 0) {
    return 1;
  } else {
    var result = 1;
    for (var i = 2; i <= D; i++) {
      result = result * i;
    }
    return result;
  }
  ';
Copy

Python

Der folgende Beispielcode erstellt eine Funktion py_udf, deren Handler-Code als udf inline ist.

CREATE OR REPLACE FUNCTION py_udf()
  RETURNS VARIANT
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.8'
  PACKAGES = ('numpy','pandas','xgboost==1.5.0')
  HANDLER = 'udf'
AS $$
import numpy as np
import pandas as pd
import xgboost as xgb
def udf():
    return [np.__version__, pd.__version__, xgb.__version__]
$$;
Copy

Der folgende Beispielcode erstellt eine Funktion dream, deren Handler sich in der Datei sleepy.py im Stagingbereich @my_stage befindet.

CREATE OR REPLACE FUNCTION dream(i int)
  RETURNS VARIANT
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.8'
  HANDLER = 'sleepy.snore'
  IMPORTS = ('@my_stage/sleepy.py')
Copy

Scala

Hier ist ein grundlegendes Beispiel für eine CREATE FUNCTION-Anweisung mit einem Inline-Handler:

CREATE OR REPLACE FUNCTION echo_varchar(x VARCHAR)
  RETURNS VARCHAR
  LANGUAGE SCALA
  RUNTIME_VERSION = 2.12
  HANDLER='Echo.echoVarchar'
  AS
  $$
  class Echo {
    def echoVarchar(x : String): String = {
      return x
    }
  }
  $$;
Copy

Hier ist ein einfaches Beispiel für CREATE FUNCTION mit einem Verweis auf einen Staging-Handler:

CREATE OR REPLACE FUNCTION echo_varchar(x VARCHAR)
  RETURNS VARCHAR
  LANGUAGE SCALA
  RUNTIME_VERSION = 2.12
  IMPORTS = ('@udf_libs/echohandler.jar')
  HANDLER='Echo.echoVarchar';
Copy

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

SQL

Erstellen Sie eine einfache skalare SQL-UDF, die eine hart codierte Approximation der mathematischen Konstante Pi zurückgibt:

CREATE FUNCTION pi_udf()
  RETURNS FLOAT
  AS '3.141592654::FLOAT'
  ;
Copy

Erstellen Sie eine einfache SQL-Tabellen-UDF, die hartcodierte Werte zurückgibt:

CREATE FUNCTION simple_table_function ()
  RETURNS TABLE (x INTEGER, y INTEGER)
  AS
  $$
    SELECT 1, 2
    UNION ALL
    SELECT 3, 4
  $$
  ;
Copy
SELECT * FROM TABLE(simple_table_function());
Copy

Ausgabe:

SELECT * FROM TABLE(simple_table_function());
+---+---+
| X | Y |
|---+---|
| 1 | 2 |
| 3 | 4 |
+---+---+
Copy

Erstellen Sie eine UDF, die mehrere Parameter akzeptiert:

CREATE FUNCTION multiply1 (a number, b number)
  RETURNS number
  COMMENT='multiply two numbers'
  AS 'a * b';
Copy

Erstellen Sie eine SQL-Tabellen-UDF namens get_countries_for_user, die die Ergebnisse einer Abfrage zurückgibt:

CREATE OR REPLACE FUNCTION get_countries_for_user ( id NUMBER )
  RETURNS TABLE (country_code CHAR, country_name VARCHAR)
  AS 'SELECT DISTINCT c.country_code, c.country_name
      FROM user_addresses a, countries c
      WHERE a.user_id = id
      AND c.country_code = a.country_code';
Copy