CREATE EXTERNAL FUNCTION¶

Siehe auch:: ALTER 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> ]
  [ REQUEST_TRANSLATOR = <request_translator_udf_name> ]
  [ RESPONSE_TRANSLATOR = <response_translator_udf_name> ]
  AS <url_of_proxy_and_resource>;

Copy

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.

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.

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

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 result_data_type

Gibt den von der Funktion zurückgegebenen Datentyp an.

API_INTEGRATION = api_integration_name

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

AS url_of_proxy_and_resource

Dies ist die Aufruf-URL des Proxydienstes (z. B. API Gateway oder API Management) 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 Statefulness).

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

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

Standard: user-defined function

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

Copy

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 = ( context_function_1 [ , context_function_2 ...] )

Dies ähnelt HEADERS, verwendet jedoch keine konstanten Zeichenfolgen, sondern bindet die Ergebnisse der Snowflake-Kontextfunktion an HTTP-Header. (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-Anforderung geschrieben wird.

Beispiel:

CONTEXT_HEADERS = (current_timestamp)

Copy

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 kundenspezifischen 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);

Copy

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

select /* */ my_external_function(1);

Copy

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

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

Im obigen Beispiel wäre der Name des Headers

sf-context-current-statement-base64

Copy

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

Gibt die maximale Anzahl von Zeilen in jedem Batch an, die an den Proxydienst gesendet werden.

Der Zweck dieses Parameters ist die Begrenzung der Batchgrößen für Remotedienste, die Speicherbeschränkungen oder andere Einschränkungen haben. Dieser Parameter ist kein Parameter zur Leistungsoptimierung. Dieser Parameter gibt eine maximale Größe an, nicht eine empfohlene Größe.

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

Snowflake empfiehlt, diesen Parameter ungesetzt zu lassen, es sei denn, der Remotedienst erfordert eine Beschränkung.

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.
GZIP.
DEFLATE.
AUTO.
- Auf AWS ist AUTO äquivalent zu GZIP.
- Auf Azure ist AUTO äquivalent zu NONE.
- Auf GCP ist AUTO äquivalent zu NONE.

Das Amazon 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.

REQUEST_TRANSLATOR = request_translator_udf_name

Dies gibt den Namen der Anforderungsübersetzerfunktion an. Weitere Informationen dazu finden Sie unter Verwendung von Anforderungs- und Antwortübersetzern mit Daten für einen Remotedienst.

RESPONSE_TRANSLATOR = response_translator_udf_name

Dies gibt den Namen der Antwortübersetzerfunktion an. Weitere Informationen dazu finden Sie unter Verwendung von Anforderungs- und Antwortübersetzern mit Daten für einen Remotedienst.

Anforderungen an die Zugriffssteuerung¶

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

Berechtigung	Objekt	Anmerkungen
CREATE EXTERNAL FUNCTION	Schema	Operating on functions also requires the USAGE privilege on the parent database and schema.
Entweder OWNERSHIP oder USAGE	API-Integration	Erforderlich zum Erstellen externer Funktionen, die auf eine API-Integration verweisen.

Eine Anleitung zum Erstellen einer kundenspezifischen Rolle mit einem bestimmten Satz 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¶

Bei Verwendung der Komprimierung setzt Snowflake die HTTP-Header „Content-Encoding“ und „Accept-Encoding“.
Die Argumenttypen und der Rückgabetyp dürfen nicht GEOGRAPHY sein.
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.

Beispiele¶

Das folgende Beispiel zeigt eine CREATE EXTERNAL FUNCTION-Anweisung, die über einen Amazon 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';

Copy

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