Erstellen einer benutzerdefinierten Funktion

Sie können eine benutzerdefinierte Funktion (UDF) mit einer der verschiedenen in Snowflake verfügbaren Methoden erstellen. Diese Methoden werden unter diesem Thema beschrieben.

Erstellen Sie eine UDF, wenn:

  1. Schreiben Sie Funktionslogik als Handler in einer von mehreren unterstützten Sprachen, darunter Python, Java und Scala.

  2. Wählen Sie ein Tool oder ein API, um die Funktion mit dem von Ihnen geschriebenen Handler zu erstellen.

    Weitere Informationen dazu finden Sie unter Tools zum Erstellen von UDFs.

    SQL

    Verwenden Sie SQL und schreiben Sie Logik in einer von mehreren Sprachen.

    Snowpark

    Verwenden Sie die Snowpark-API für Java, Python oder Scala.

    Befehlszeile

    Ausführen von CLI-Befehlen, um die Funktion zu erstellen.

    Python API

    Ausführen von clientseitigen Python-Befehle, um die Funktion zu erstellen.

    REST

    Stellen von Anfragen an eine RESTful API, um die Funktion zu erstellen.

  3. Führen Sie die Funktion mit einem der verschiedenen Tools aus, je nach Ihren Bedürfnissen.

Tools zum Erstellen von UDFs

Sie können eine UDF mit einer von mehreren in Snowflake verfügbaren Methoden erstellen, je nachdem, welche Sprache und welche Fähigkeiten Sie haben. Wählen Sie aus der folgenden Tabelle das für Ihre Bedürfnisse geeignete Tool aus.

Sprache

Ansatz

SQL

Führen Sie einen SQL-Befehl aus, z. B. über die Snowsight.

Führen Sie den Befehl SQL CREATE FUNCTION aus, um eine Funktion mit Handler-Code zu erstellen, der in einer der folgenden Sprachen geschrieben wurde:

Java, Python, oder Scala mit Snowpark

Schreiben Sie Code in einer der unterstützten Sprachen und führen Sie den Code dann lokal aus, um Operationen in Snowflake durchzuführen.

Führen Sie Client-Code aus, der Snowpark-APIs in einer der folgenden Sprachen verwendet.

Befehlszeile

Erstellen und verwalten Sie Snowflake-Entitäten, indem Sie Befehle über die Befehlszeile ausführen.

Führen Sie die Befehle der Snowflake CLI aus.

Python

Schreiben Sie auf dem Client Code, der Verwaltungsoperationen auf Snowflake ausführt.

Führen Sie Code aus, der die Snowflake Python-API verwendet.

RESTful APIs (sprachunabhängig)

Stellen Sie Anfragen an RESTful-Endpunkte, um Snowflake Entitäten zu erstellen und zu verwalten.

Stellen Sie eine Anfrage zur Erstellung einer Prozedur mit Snowflake REST API

Wichtige Eigenschaften

Im Folgenden werden einige der Eigenschaften beschrieben, die beim Erstellen einer Funktion erforderlich sind oder üblicherweise verwendet werden.

Funktionsname:

Der Funktionsname muss nicht mit dem Namen des Handlers übereinstimmen. Für weitere Informationen zu Einschränkungen und Konventionen bei der Namensvergabe finden Sie unter Benennen und Überladen von Prozeduren und UDFs.

Argumente:

Weitere Informationen zu den Anforderungen finden Sie unter Definieren von Argumenten für UDFs und gespeicherte Prozeduren.

Rückgabetyp:

Weitere Informationen zum Zuordnen von SQL-Datentypen zu Handler-Datentypen in Snowflake finden Sie unter Zuordnung von Datentypen zwischen SQL und Handler-Sprachen.

Handler-Name:

Falls erforderlich, ist dies der Name der Klasse oder Methode, die den Code enthält, der bei Ausführung der Funktion ausgeführt wird. Die Angabe eines Handler-Namens ist nur für Handler erforderlich, die in Java, Python oder Scala geschrieben wurden. Bei JavaScript- und SQL-Handlern wird der gesamte Inline-Code als Handler ausgeführt.

Abhängigkeiten:

Bei einem in Java, Python oder Scala geschriebenen Handler müssen Sie möglicherweise auch die Snowpark-Bibliothek angeben, z. B. bei der Erstellung der Funktion.

Weitere Informationen zur Bereitstellung der Abhängigkeiten für den Handler finden Sie unter Abhängigkeiten für Code zur Verfügung stellen.

Laufzeit der Handler-Sprache:

Wenn die Handler-Sprache Java, Python oder Scala ist, geben Sie die Laufzeitversion an, um anzugeben, welche unterstützte Laufzeitversion verwendet werden soll. Denken Sie daran, dass sich die Standardversion im Laufe der Zeit ändern wird, wenn Sie sie verwenden.

Anforderungen an die Zugriffssteuerung

Eine Rolle, die zur Ausführung dieser Operation verwendet wird, muss mindestens die folgenden Berechtigungen haben:

Berechtigung

Objekt

Anmerkungen

CREATE FUNCTION

Schema

Die Berechtigung ermöglicht nur die Erstellung von benutzerdefinierten Funktionen im Schema.

Wenn Sie die Erstellung von Datenmetrikfunktionen aktivieren möchten, muss die Rolle über die Berechtigung CREATE DATA METRIC FUNCTION verfügen.

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.

USAGE-Berechtigung für die übergeordnete Datenbank und das Schema ist erforderlich, um Operationen an einem beliebigen Objekt in einem Schema durchzuführen.

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

Die folgenden Anmerkungen beschreiben die Nutzungshinweise für die Sprachen, die beim Schreiben von Handlern unterstützt werden. Obwohl sich die Hinweise in den folgenden Abschnitten auf Klauseln des SQL-Befehls CREATE FUNCTION beziehen, werden diese Klauseln in der Regel auf andere Weise in anderen Tools dargestellt, die Sie zum Erstellen von Funktionen verwenden können.

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.

  • 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.

  • 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.

  • Mit der PACKAGES-Klausel können Sie Paketnamen und Versionsnummern für systemdefinierte Snowflake-Abhängigkeiten angeben, z. B. für die von Snowpark. 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, je nachdem, ob Sie mit einem aktiven Snowflake-Warehouse verbunden sind.

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

    • Ausführungszeit — Wenn Sie nicht mit einem aktiven Snowflake-Warehouse verbunden sind, wird die UDF zwar 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 den JavaScript-Code nicht zum Zeitpunkt der Erstellung einer UDF. Mit anderen Worten: Die Erstellung der UDF gelingt unabhängig davon, ob der Code gültig ist. Wenn der Code nicht gültig ist, gibt Snowflake Fehler zurück, wenn die UDF zur Abfragezeit aufgerufen wird.

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.

  • Mit der PACKAGES-Klausel können Sie Paketnamen und Versionsnummern für systemdefinierte Snowflake-Abhängigkeiten angeben, z. B. für die von Snowpark. 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, je nachdem, ob Sie mit einem aktiven Snowflake-Warehouse verbunden sind.

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

    • Ausführungszeit — Wenn Sie nicht mit einem aktiven Snowflake-Warehouse verbunden sind, wird die UDF zwar 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.

Eine UDF mit SQL erstellen

Sie können eine UDF mit SQL erstellen, indem Sie die folgenden Schritte ausführen.

Verwenden der CREATE FUNCTION-Anweisung zum Verknüpfen der Handler-Methode mit dem UDF-Namen

Zum Erstellen einer UDF müssen Sie die folgenden Schritte ausführen:

  1. Schreiben Sie den Handler-Code, der bei Aufruf der UDF ausgeführt werden soll.

    Sie können eine der unterstützten Handler-Sprachen verwenden. Weitere Informationen dazu finden Sie unter Unterstützte Sprachen und Tools.

  2. Legen Sie fest, ob Sie den Handler-Code inline in der SQL-Anweisung CREATE FUNCTION verwenden möchten oder auf den Handler-Code in einem Stagingbereich verweisen möchten.

    Beide Methoden haben Vor- und Nachteile. Weitere Informationen dazu finden Sie unter Speichern von Handler-Code inline oder in einem Stagingbereich.

  3. Führen Sie eine CREATE FUNCTION-Anweisung in SQL aus, und geben Sie dabei die Eigenschaften der Funktion an.

    Der Code im folgenden Beispiel erstellt eine UDF namens function_name mit dem Inline-Handler HandlerClass.handlerMethod.

    create function function_name(x integer, y integer)
      returns integer
      language java
      handler='HandlerClass.handlerMethod'
      target_path='@~/HandlerCode.jar'
      as
      $$
          class HandlerClass {
              public static int handlerMethod(int x, int y) {
                return x + y;
              }
          }
      $$;
    
    Copy

    Im Folgenden werden einige der Eigenschaften beschrieben, die beim Erstellen einer Funktion erforderlich sind oder üblicherweise verwendet werden.

    • Funktionsname.

      Der UDF-Name muss nicht mit dem Namen der in Java geschriebenen Handler-Methode übereinstimmen. Die CREATE FUNCTION-Anweisung verknüpft den UDF-Namen mit dem Handler.

      Für weitere Informationen zu Einschränkungen und Konventionen bei der Namensvergabe finden Sie unter Benennen und Überladen von Prozeduren und UDFs.

    • Funktionsargumente, falls vorhanden.

      Siehe Definieren von Argumenten für UDFs und gespeicherte Prozeduren.

    • Rückgabetyp mit der RETURNS-Klausel.

      Bei einem skalaren Rückgabewert gibt die RETURNS-Klausel einen einzelnen Rückgabetyp an. Bei einem tabellarischen Rückgabewert gibt RETURNS das Schlüsselwort TABLE an, das den Spaltentyp im tabellarischen Rückgabewert angibt.

      Weitere Informationen zum Zuordnen von SQL-Datentypen zu Handler-Datentypen in Snowflake finden Sie unter Benennen und Überladen von Prozeduren und UDFs.

    • Handler-Name mit der HANDLER-Klausel.

      Falls erforderlich, ist dies der Name der Klasse oder Methode, die den Code enthält, der bei Aufruf der UDF ausgeführt wird. Die Angabe eines Handler-Namens ist nur für Handler erforderlich, die in Java und Python geschrieben wurden. Bei JavaScript- und SQL-Handlern wird der gesamte Inline-Code als Handler ausgeführt.

      In der folgenden Tabelle wird gezeigt, welche Form der Wert der HANDLER-Klausel in Abhängigkeit von der Handler-Sprache und dem Funktionstyp annimmt.

      Sprache des Handlers

      UDF

      UDTF

      Java

      Klassen- und Methodenname.

      Beispiel: MyClass.myMethod

      Nur Klassenname. Der Name der Handler-Methode wird durch die erforderliche Schnittstelle vorgegeben.

      JavaScript

      Keine.

      Keine.

      Python

      Klassen- und Methodenname bei Verwendung einer Klasse, ansonsten Funktionsname.

      Beispiel: module.my_function oder my_function

      Nur Klassenname. Der Name der Handler-Methode wird durch die erforderliche Schnittstelle vorgegeben.

      SQL

      Keine.

      Keine.

    • Vom Handler benötigte Abhängigkeiten, falls vorhanden, unter Verwendung der IMPORTS- oder PACKAGES-Klausel.

      Weitere Informationen zur Bereitstellung der Abhängigkeiten für den Handler finden Sie unter Abhängigkeiten für Code zur Verfügung stellen.

    • Laufzeitumgebung der Handler-Sprache mit Klausel RUNTIME_VERSION.

      Wenn die Handler-Sprache Java oder Python ist, verwenden Sie die RUNTIME_VERSION-Klausel, um anzugeben, welche unterstützte Laufzeitversion verwendet werden soll. Wenn Sie die Klausel weglassen, verwendet Snowflake die Standardeinstellung, die sich in Zukunft ändern kann.