Kategorien:

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

CREATE EXTERNAL FUNCTION

Erstellt eine neue externe Funktion.

Siehe auch:

ALTER EXTERNAL FUNCTION, SHOW EXTERNAL FUNCTIONS, DROP FUNCTION, DESCRIBE FUNCTION, CREATE API INTEGRATION

Syntax

CREATE [ OR REPLACE ] [ SECURE ] EXTERNAL 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 ]
  [ COMMENT = '<string_literal>' ]
  API_INTEGRATION = <api_integration_name>
  [ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  [ COMPRESSION = <compression_type> ]
  AS <url_of_proxy_and_resource>;

Erforderliche Parameter

Name:

Gibt den Bezeichner der Funktion an.

Der Bezeichner kann den Schemanamen und den Datenbanknamen sowie den Funktionsnamen enthalten.

Der Bezeichner muss für das Schema, in dem die Funktion erstellt wird, nicht eindeutig sein, da Funktionen durch ihren Namen und ihre Argumenttypen identifiziert und aufgelöst werden. Die Signatur (Name und Datentypen der Argumente) muss jedoch innerhalb des Schemas eindeutig sein.

Der Name muss den Snowflake-Regeln für Bezeichner folgen. Weitere Details dazu finden Sie unter Anforderungen an Bezeichner.

Wenn Sie für Name den Namen des Remotedienstes verwenden, wird die Beziehung deutlicher. Dies ist jedoch nicht erforderlich.

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

Gibt die Argumente/Eingaben für die externe Funktion an. Diese sollten den Argumenten entsprechen, die der Remotedienst erwartet.

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

RETURNS ...

Gibt den von der Funktion zurückgegebenen Datentyp an.

API-Integrationsname

Dies ist der Name des API-Integrationsobjekts, das zur Authentifizierung des Aufrufs an den Proxydienst verwendet werden soll.

URL_von_Proxy_und_Ressource

Dies ist die Aufruf-URL des Proxydienstes (z. B. API Gateway) und der Ressource, über die Snowflake den Remotedienst aufruft.

Optionale Parameter

SECURE

Gibt an, dass die Funktion sicher ist. Wenn eine Funktion sicher ist, werden die URL, der HTTP-Header und die Kontext-Header vor allen Benutzern ausgeblendet, die nicht Eigentümer der Funktion sind.

[ [ NOT ] NULL ]

Diese Klausel gibt an, ob die Funktion auch NULL-Werte oder nur NON-NULL-Werte zurückgeben kann. Wenn NOT NULL angegeben ist, darf die Funktion nur Nicht-NULL-Werte zurückgeben. Wenn NULL angegeben ist, kann die Funktion NULL-Werte zurückgeben.

Standard: Der Standardwert ist NULL (d. h. die Funktion kann NULL-Werte zurü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 externe 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 liefert immer dasselbe Ergebnis, wenn sie mit den gleichen Eingabewerten aufgerufen wird. Snowflake führt keine Überprüfung der Unveränderlichkeit durch und gibt keine Garantie dafür. Der Remotedienst muss so entwickelt werden, dass er sich auf diese Weise verhält. Die Angabe von IMMUTABLE für eine Funktion, die unterschiedliche Werte für dieselbe Eingabe zurückgibt, führt zu einem undefinierten Verhalten.

Standard: VOLATILE

Snowflake empfiehlt, dies explizit festzulegen, anstatt die Standardeinstellung zu akzeptieren. Wenn Sie die Flüchtigkeit explizit festlegen, wird die Fehlerwahrscheinlichkeit verringert und den Benutzern mitgeteilt, wie sich die Funktion verhält. (Der Befehl SHOW EXTERNAL FUNCTIONS zeigt an, ob eine Funktion flüchtig oder unveränderlich ist.)

Wichtige zusätzliche Informationen zu den Eigenschaften VOLATILE vs. IMMUTABLE von externen Funktionen finden Sie unter Funktion als „Flüchtig“ oder „Unveränderlich“ kategorisieren.

COMMENT = 'Zeichenfolgenliteral'

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

[ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]

Mit dieser Klausel können Benutzer Schlüsselwert-Metadaten angeben, die bei jeder Anforderung gesendet werden. Der Ersteller der externen Funktion entscheidet, was in die Header aufgenommen wird. Der Aufrufer hat keine Kontrolle darüber. Snowflake stellt allen angegebenen Headernamen das Präfix „sf-custom-“ voran und sendet sie als HTTP-Header.

Der Wert muss eine konstante Zeichenfolge sein, kein Ausdruck.

Hier finden Sie ein Beispiel:

headers = (
    'volume-measure' = 'liters',
    'distance-measure' = 'kilometers'
)

Dadurch fügt Snowflake jeder HTTPS-Anforderung zwei HTTP-Header mit entsprechenden Werten hinzu: sf-custom-volume-measure und sf-custom-distance-measure.

Die Regeln für Headernamen unterscheiden sich von den Regeln für Snowflake-Datenbankbezeichnern. Headernamen können aus den meisten sichtbaren Standard-ASCII-Zeichen (Dezimal 32-126) bestehen, mit Ausnahme der folgenden:

  • `` `` (das Leerzeichen)

  • (

  • )

  • ,

  • /

  • :

  • ;

  • <

  • >

  • =

  • "

  • ?

  • @

  • [

  • ]

  • \

  • {

  • }

  • _

Beachten Sie insbesondere, dass der Unterstrich in Headernamen nicht zulässig ist.

Name und Wert des Headers werden in einfache Anführungszeichen eingeschlossen. Daher müssen alle einfachen Anführungszeichen im Namen oder Wert des Headers mit dem Backslash-Zeichen maskiert werden.

Wenn das Backslash-Zeichen als Literalzeichen in einem Headerwert verwendet wird, muss es in Escape-Zeichen eingeschlossen werden.

In Headerwerten sind sowohl Leerzeichen als auch Tabulatoren zulässig. Headerwerte sollten jedoch nicht mehr als ein Leerzeichen in einer Zeile enthalten. Diese Einschränkung gilt für Kombinationen von Leerzeichen (z. B. ein Leerzeichen gefolgt von einer Registerkarte) sowie für einzelne Leerzeichen (z. B. zwei Leerzeichen in einer Reihe).

Wenn der Autor seine Funktion als sicher markiert (mit CREATE SECURE EXTERNAL FUNCTION...), sind die Header, die Kontextheader, die binären Kontextheader und die URL für Benutzer der Funktion nicht sichtbar.

Die Summe der Größen von Headernamen und Headerwerten einer externen Funktion muss kleiner oder gleich 8 KB sein.

CONTEXT_HEADERS ...

Dies ähnelt headers, verwendet jedoch keine konstanten Zeichenfolgen, sondern bindet die Ergebnisse der Snowflake-Kontextfunktion an HTTP-Header. (Eine Liste der Snowflake-Kontextfunktionen finden Sie unter Kontextfunktionen.)

Die Funktionsnamen dürfen in Anführungszeichen gesetzt werden.

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

Beispiel:

context_headers = (current_timestamp)

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

Die in Kontextheadernamen und -werten zulässigen Zeichen sind dieselben wie die in benutzerdefinierten Headernamen und -werten zulässigen Zeichen.

Kontextfunktionen können Zeichen generieren, die in HTTP-Headerwerten unzulässig sind, einschließlich (aber nicht beschränkt auf):

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

Angenommen, die Kontextfunktion CURRENT_STATEMENT() gibt Folgendes zurück:

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

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

select /* */ my_external_function(1);

Um sicherzustellen, dass Remotedienste auf 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-Header gesendete Wert das Ergebnis von folgendem Aufruf:

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

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

Im obigen Beispiel wäre der Name des Headers

sf-context-current-statement-base64

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

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

MAX_BATCH_ROWS = <integer>

Dies gibt die maximale Anzahl von Zeilen in jedem Batch an, die an den Proxydienst gesendet werden. Die Batchgröße kann kleiner sein, und normalerweise ist der letzte Batch für eine Abfrage kleiner, es sei denn, die Gesamtzahl der gesendeten Zeilen ist ein Vielfaches der Batchgröße.

Wenn Sie MAX_BATCH_ROWS nicht angeben, schätzt Snowflake die optimale Batchgröße und verwendet diese.

Der Wert muss eine positive Ganzzahl zwischen 1 und 2147483647 sein.

COMPRESSION = <compression_type>

Bei Angabe dieser Klausel wird die JSON-Nutzlast komprimiert, wenn sie von Snowflake an den Proxydienst gesendet und vom Proxydienst an Snowflake zurückgesendet wird.

Gültige Werte:

  • NONE.

  • AUTO. (Auf AWS ist dies äquivalent zu GZIP.)

  • GZIP.

  • DEFLATE.

Das Amazon AWS API Gateway komprimiert/dekomprimiert Anforderungen automatisch. Weitere Informationen zur Komprimierung und Dekomprimierung von Amazon API Gateway finden Sie unter: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gzip-compression-decompression.html

Weitere Informationen zur Komprimierung und Dekomprimierung anderer Cloudplattform-Proxydienste finden Sie in der Dokumentation zu diesen Cloudplattformen.

Der Standardwert ist AUTO.

Nutzungshinweise

  • Um eine externe Funktion auszuführen, muss eine Rolle die Berechtigung USAGE oder OWNERSHIP für die externe Funktion haben.

  • Bei Verwendung der Komprimierung setzt Snowflake die HTTP-Header „Content-Encoding“ und „Accept-Encoding“.

  • Unter AWS sind für externe Funktionen regionale Endpunkte erforderlich. Weitere Details dazu finden Sie unter Amazon AWS API Gateway.

  • Die Argumenttypen und der Rückgabetyp dürfen nicht GEOGRAPHY sein.

Beispiele

Das folgende Beispiel zeigt eine CREATE EXTERNAL FUNCTION-Anweisung, die über einen Amazon AWS API Gateway-Proxydienst aufgerufen wird:

create or replace external function local_echo(string_col VARCHAR)
    returns variant
    api_integration = demonstration_external_api_integration_01
    as 'https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo';

In diesem Beispiel:

  • local_echo ist der Name, der aus einer SQL-Anweisung aufgerufen wird. (Beispielsweise können Sie SELECT local_echo(varchar_column) ...; ausführen.)

  • string_col VARCHAR enthält Name und Datentyp der Eingabeparameter. Eine externe Funktion kann 0, 1 oder mehrere Eingabeparameter haben.

  • variant ist der Datentyp des von der externen Funktion zurückgegebenen Werts.

  • Der Name demonstration_external_api_integration_01 ist der Name der API-Integration, die zuvor in der Anweisung CREATE API INTEGRATION erstellt wurde.

  • Die URL „https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo“ ist die Zeichenfolge, mit der Proxydienst und Proxyressource identifiziert werden. Ein HTTP-POST-Befehl wird an diese URL gesendet.