Kategorien:: DDL für benutzerdefinierte Funktionen, externe Funktionen und gespeicherte Prozeduren

CREATE FUNCTION¶

Erstellt eine neue UDF (benutzerdefinierte Funktion). Eine UDF kann entweder einen SQL-Ausdruck oder JavaScript-Code enthalten und entweder skalare oder tabellarische Ergebnisse liefern.

Siehe auch:: ALTER FUNCTION, SHOW USER FUNCTIONS

Syntax¶

CREATE [ OR REPLACE ] [ SECURE ] FUNCTION <name> ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  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>'

Erforderliche Parameter¶

Name ( [ Argumentname Argumentdatentyp ] [ , ... ] )

Gibt den Bezeichner (und optional ein oder mehrere Argumente/Eingaben) für die UDF an. Der Bezeichner muss für das Schema, in dem die UDF erstellt wird, nicht eindeutig sein, da UDFs durch ihren Namen und ihre Argumenttypen identifiziert und aufgelöst werden.

Der Bezeichner muss jedoch mit einem alphabetischen Zeichen beginnen und darf keine Leer- oder Sonderzeichen enthalten, es sei denn, die gesamte Bezeichnerzeichenfolge wird in doppelte Anführungszeichen gesetzt (z. B. "My object"). Bei Bezeichnern, die in doppelte Anführungszeichen eingeschlossen sind, ist auch die Groß-/Kleinschreibung zu beachten.

Weitere Details dazu finden Sie unter Anforderungen an Bezeichner.

RETURNS ...

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

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

TABLE ( Spaltenname Spaltendatentyp , ... ): Erstellt eine Tabellen-UDF, die tabellarische Ergebnisse mit den angegebenen Tabellenspalten und Spaltentypen zurückgibt.

AS Funktionsdefinition

Definiert den Code, der von der UDF ausgeführt wird. Der Inhalt hängt vom Typ der erstellten UDF ab:

SQL-UDF: Jeder gültige SQL-Ausdruck. Weitere Informationen zu SQL-UDFs einschließlich Beispielen finden Sie unter Übersicht zu UDFs.

JavaScript-UDF: Jedes gültige JavaScript. Weitere Informationen zu JavaScript-UDFs einschließlich Beispielen finden Sie unter JavaScript UDFs.

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

Optionale Parameter¶

SECURE

Gibt an, dass die Funktion sicher ist. Weitere Informationen zu sicheren Funktionen finden Sie unter Sichere UDFs.

LANGUAGE JAVASCRIPT

Gibt an, dass Funktionsdefinition JavaScript-Code enthält. Andernfalls muss Funktionsdefinition einen SQL-Ausdruck enthalten.

Standard: Kein Wert (d. h. SQL-UDF wird erstellt)

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.

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 = 'Zeichenfolgenliteral'

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

Nutzungshinweise¶

Die Trennzeichen um die Funktionsdefinition können einfache Anführungszeichen oder doppelte Dollarzeichen sein. Eine Verwendung von $$ als Trennzeichen vereinfacht das Schreiben von gespeicherten Prozeduren, die einfache Anführungszeichen enthalten. Einige der folgenden Beispiele verwenden $$ als Trennzeichen.
Wenn als Trennzeichen für den Hauptteil der Funktion das einfache Anführungszeichen verwendet wird, müssen alle Anführungszeichen innerhalb von Funktionsdefinition (z. B. Zeichenfolgenliterale) mit einfachen Anführungszeichen als Escape-Zeichen versehen werden.
Funktionsdefinition hat Größenbeschränkungen. Die maximal zulässige Größe kann sich ändern.
Snowflake validiert JavaScript-Code nicht zur UDF-Erstellungszeit (d. h. die Erstellung der UDF ist unabhängig davon, ob der Code gültig ist, erfolgreich). Wenn der Code nicht gültig ist, werden bei Aufruf der UDF zur Abfragezeit Fehler zurückgegeben. Weitere Details dazu finden Sie unter JavaScript UDFs.
Die optionale [ [ NOT ] NULL ]-Klausel gibt an, ob die Funktion NULL-Werte zurückgeben kann oder nur Nicht-NULL-Werte. Der Standardwert ist NULL (d. h. die Funktion kann NULL zurückgeben).

Bemerkung

Derzeit wird die NOT NULL-Klausel nur für JavaScript-UDFs erzwungen, nicht für SQL-UDFs. Als NOT NULL deklarierte SQL-UDFs können NULL-Werte zurückgeben. Snowflake empfiehlt Kunden, 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.

Beispiele¶

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'
  ;

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
  $$
  ;

SELECT * FROM TABLE(simple_table_function());

Ausgabe:

+---+---+
| X | Y |
|---+---|
| 1 | 2 |
| 3 | 4 |
+---+---+

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';

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;
  }
  ';