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ß- und 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 Skalar-UDF, die einen Einzelwert mit dem angegebenen Datentyp zurückgibt.

  • TABLE ( Spaltenname Spaltendatentyp , ... ) Erstellt eine UDF-Tabelle, 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 erstellten UDF-Typ ab:

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

  • JavaScript UDF: Jedes gültige JavaScript. Weitere Informationen zu JavaScript UDFs, einschließlich Beispiele, 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 Ergebnisrückgabe an:

  • VOLATILE: 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

  • Sie können eine andere Zeichenfolge als ein einfaches Anführungszeichen verwenden, um den Hauptteil von der UDF abzugrenzen. Beispielsweise können Sie eine Folge von zwei Dollarzeichen („$$“) verwenden. Einige der folgenden Beispiele verwenden „$$“ als Trennzeichen.

  • Wenn das Trennzeichen für den Hauptteil der Funktion das einfache Anführungszeichen ist, 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. SQL-UDFs deklariert als NOT NULL 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;
  }
  ';