CREATE FUNCTION (Snowpark Container Services)¶

Syntax¶

CREATE [ OR REPLACE ] FUNCTION <name> ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  SERVICE = <service_name>
  ENDPOINT = <endpoint_name>
  [ COMMENT = '<string_literal>' ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , <context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  AS '<http_path_to_request_handler>'

Erforderliche Parameter¶

name

Gibt den Bezeichner (name) und alle Eingabeargumente für die Funktion an.

• Der Bezeichner muss für das Schema, in dem die Funktion erstellt wird, nicht eindeutig sein, da Funktionen durch die Kombination aus Name und Argumenttypen identifiziert und aufgelöst werden.

• Der Bezeichner muss 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. „Mein Objekt“). Bei Bezeichnern, die in doppelte Anführungszeichen eingeschlossen sind, ist auch die Groß-/Kleinschreibung zu beachten. Siehe Anforderungen an Bezeichner.

( [ arg_name arg_data_type ] [ , ... ] )

Gibt die Argumente/Eingaben für die Dienstfunktion an. Diese sollten den Argumenten entsprechen, die der Dienst erwartet.

Wenn keine Argumente vorhanden sind, fügen Sie die Klammern ohne Argumentnamen und Datentypen ein.

RETURNS result_data_type

Gibt den Datentyp des von der Funktion zurückgegebenen Ergebnisses an.

SERVICE = service_name

Gibt den Namen des Snowpark Container Services-Dienstes an.

ENDPOINT = endpoint_name

Gibt den Namen des Endpunktes an, wie er in der Dienstspezifikation definiert ist.

AS http_path_to_request_handler

Gibt den HTTP-Pfad zu dem Dienstcode an, der beim Aufruf der Funktion ausgeführt wird.

Optionale Parameter¶

[ [ NOT ] NULL ]

Gibt an, ob die Funktion auch NULL-Werte oder nur NON-NULL-Werte zurückgeben kann. Die Voreinstellung ist NULL (das heißt, die Funktion kann NULLzurückgeben).

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

Gibt das Verhalten der Funktion 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 Funktionen Null-Eingaben verarbeiten und Nicht-Null-Werte zurückgeben, auch wenn eine Eingabe Null ist:

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

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

Standard: CALLED ON NULL INPUT

{ VOLATILE | IMMUTABLE }

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

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

• IMMUTABLE: Die Funktion 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 Funktion, die für dieselbe Eingabe unterschiedliche Werte zurückgibt, führt zu einem undefinierten Verhalten.

Standard: VOLATILE

[ MAX_BATCH_ROWS = integer ]

Gibt die Stapelgröße beim Senden von Dienst zur Erhöhung der Parallelität an

COMMENT = 'string_literal'

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

Standard: user-defined function

CONTEXT_HEADERS = ( context_function_1 [ , context_function_2 ...] )

Damit werden die Ergebnisse der Snowflake-Kontextfunktion an die HTTP-Header gebunden. (Weitere Informationen zu Snowflake-Kontextfunktionen finden Sie unter Kontextfunktionen.)

Nicht alle Kontextfunktionen werden in Kontext-Headern unterstützt. Folgendes wird unterstützt:

• CURRENT_ACCOUNT()

• CURRENT_CLIENT()

• CURRENT_DATABASE()

• CURRENT_DATE()

• CURRENT_IP_ADDRESS()

• CURRENT_REGION()

• CURRENT_ROLE()

• CURRENT_SCHEMA()

• CURRENT_SCHEMAS()

• CURRENT_SESSION()

• CURRENT_STATEMENT()

• CURRENT_TIME()

• CURRENT_TIMESTAMP()

• CURRENT_TRANSACTION()

• CURRENT_USER()

• CURRENT_VERSION()

• CURRENT_WAREHOUSE()

• LAST_QUERY_ID()

• LAST_TRANSACTION()

• LOCALTIME()

• LOCALTIMESTAMP()

Wenn Funktionsnamen in der CONTEXT_HEADERS-Klausel aufgeführt sind, dürfen die Funktionsnamen nicht in Anführungszeichen gesetzt werden.

Snowflake stellt dem Header sf-context voran, bevor er in die HTTP-Anfrage geschrieben wird.

Beispiel:

CONTEXT_HEADERS = (current_timestamp)

Copy

In diesem Beispiel schreibt Snowflake den Header sf-context-current-timestamp in die HTTP-Anforderung.

Kontextfunktionen können Zeichen erzeugen, die in HTTP-Header-Werten nicht zulässig sind, einschließlich (aber nicht beschränkt auf) die folgenden:

• Neue-Zeile-Zeichen

• Ä

• Î

• ß

• ë

• ¬

• ±

• ©

• ®

Snowflake ersetzt jede Sequenz aus einem oder mehreren unzulässigen Zeichen durch ein Leerzeichen. (Die Ersetzung erfolgt pro Sequenz, nicht pro Zeichen.)

Nehmen wir zum Beispiel an, dass die Kontextfunktion CURRENT_STATEMENT() Folgendes zurückgibt:

select
  /*ÄÎß묱©®*/
  my_service_function(1);

Copy

Der in sf-context-current-statement gesendete Wert lautet:

select /* */ my_service_function(1);

Copy

Um sicherzustellen, dass Ihr Dienstcode das ursprüngliche Ergebnis der Kontextfunktion (mit den unzulässigen Zeichen) zugreifen können, auch wenn unzulässige Zeichen ersetzt wurden, sendet Snowflake auch einen binären Kontextheader, der das in Base64-codierte Ergebnis der Kontextfunktion enthält.

Im obigen Beispiel ist der im Base64-codierten Header gesendete Wert das Ergebnis des folgenden Aufrufs:

base64_encode('select\n/ÄÎß묱©®/\nmy_service_function(1)')

Copy

Der Remotedienst ist für die Dekodierung des Base64-Werts verantwortlich, falls erforderlich.

Jeder dieser Base64-Header ist gemäß der folgenden Konvention benannt:

sf-context-<context-function>-base64

Copy

In dem obigen Beispiel würde der Name des Headers wie folgt lauten:

sf-context-current-statement-base64

Copy

Wenn keine Kontextheader gesendet werden, werden auch keine base64-Kontextheader gesendet.

Wenn die an eine Dienstfunktion gesendeten Zeilen auf mehrere Batches aufgeteilt sind, enthalten alle Batches dieselben Kontextheader und dieselben binären Kontextheader.

Anforderungen an die Zugriffssteuerung¶

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

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¶

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

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

Beispiele¶

In Tutorial-1 erstellen Sie die folgende Dienstunktion:

CREATE FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE=echo_service
  ENDPOINT=echoendpoint
  AS '/echo';

Diese Funktion stellt eine Verbindung mit dem spezifischen Endpunkt in ENDPOINT des in SERVICE angegebenen Dienstes her. Wenn Sie diese Funktion aufrufen, sendet Snowflake eine Anforderung an den Pfad /echo innerhalb des Dienstcontainers.

Beachten Sie Folgendes:

• Die Funktion my_echo_udf nimmt eine Zeichenfolge als Eingabe entgegen und gibt eine Zeichenfolge zurück.

• Die Eigenschaft SERVICE bezeichnet den Dienst (echo_service), und die Eigenschaft ENDPOINT bezeichnet den benutzerfreundlichen Namen des Endpunkts (echoendpoint).

• Die AS '/echo' gibt den Pfad für den Dienst an. In echo_service.py (siehe Dienstcode) verknüpft der @app.post Decorator diesen Pfad mit der Funktion echo.