Snowflake Scripting-UDFs¶
Snowflake unterstützt benutzerdefinierte SQL-Funktionen (UDFs), die prozedurale Snowflake Scripting-Sprache enthalten. Diese UDFs werden als Snowflake Scripting-UDFs bezeichnet.
Snowflake Scripting-UDFs können in einer SQL-Anweisung aufgerufen werden, z. B. einer SELECT-Anweisung oder einer INSERT-Anweisung. Daher sind sie flexibler als eine gespeicherte Prozedur in Snowflake Scripting, die nur in einem SQL CALL-Befehl aufgerufen werden kann.
Allgemeine Nutzung¶
Ein Snowflake Scripting-UDF wertet prozeduralen Code aus und gibt einen skalaren (d. h. einzelnen) Wert zurück.
Sie können die folgende Teilmenge der Snowflake Scripting-Syntax in Snowflake Scripting-UDFs verwenden:
Unterstützte Datentypen¶
Snowflake Scripting-UDFs unterstützen die folgenden Datentypen für Eingabeargumente und Rückgabewerte:
Numerische Datentypen (z. B. INTEGER, NUMBER und FLOAT)
Zeichenfolgen- und Binärdatentypen (zum Beispiel VARCHAR und BINARY)
Datentypen für Datum und Uhrzeit (zum Beispiel DATE, TIME und TIMESTAMP)
Logische Datentypen (z. B. BOOLEAN)
Snowflake Scripting-UDFs unterstützen die folgenden Datentypen nur für Eingabeargumente:
Semistrukturierte Datentypen (zum Beispiel VARIANT, OBJECT und ARRAY)
Strukturierte Datentypen (z. B. ARRAY, OBJECT und MAP)
Einschränkungen¶
Die folgenden Einschränkungen gelten für Snowflake Scripting-UDFs:
Die folgenden Typen der Snowflake Scripting-Syntax werden in Snowflake Scripting-UDFs nicht unterstützt:
SQL-Anweisungen werden in Snowflake Scripting-UDFs (einschließlich SELECT, INSERT, UPDATE und so weiter) nicht unterstützt.
Snowflake Scripting-UDFs können nicht als Tabellenfunktionen definiert werden.
Die folgenden Ausdrucksarten werden in Snowflake Scripting-UDFs nicht unterstützt:
Benutzerdefinierte Funktionen
Aggregationsfunktionen
Fensterfunktionen
Snowflake Scripting-UDFs können beim Erstellen einer materialisierten Ansicht nicht verwendet werden.
Snowflake Scripting-UDFs können nicht verwendet werden, wenn Zeilenzugriffsrichtlinien und Maskierungsrichtlinien erstellt werden.
Snowflake Scripting-UDFs können nicht verwendet werden, um einen Standard-Spaltenwert anzugeben.
Snowflake Scripting-UDFs können nicht in einem COPY INTO-Befehl zum Laden und Entladen von Daten verwendet werden.
Snowflake Scripting-UDFs können nicht memoisierbar sein.
Snowflake Scripting-UDFs haben einen Grenzwert von 500 Eingabeargumenten.
Sie können keine Nachrichten für Snowflake Scripting-UDFs protokollieren.
Beispiele¶
In den folgenden Beispielen werden Snowflake Scripting-UDFs erstellt und aufgerufen:
Erstellen einer Snowflake Scripting-UDF mit Ausnahmebehandlung
Erstellen einer Snowflake Scripting-UDF, die einen Wert für eine INSERT-Anweisung zurückgibt
Erstellen einer Snowflake Scripting-UDF, die in WHERE- und ORDER BY-Klauseln aufgerufen wird
Snowflake Scripting-UDF mit Variablen erstellen¶
Erstellen Sie eine Snowflake Scripting-UDF, die den Gewinn anhand der Werte von zwei Argumenten berechnet:
CREATE OR REPLACE FUNCTION calculate_profit(
cost NUMBER(38, 2),
revenue NUMBER(38, 2))
RETURNS number(38, 2)
LANGUAGE SQL
AS
DECLARE
profit NUMBER(38, 2) DEFAULT 0.0;
BEGIN
profit := revenue - cost;
RETURN profit;
END;
Bemerkung
Wenn Sie Snowflake-CLI, SnowSQL und |sf-legacy-interface-link|oder die Methode execute_stream
oder execute_string
in Python-Konnektor-Code verwenden, müssen an diesem Beispiel geringfügige Änderungen vorgenommen werden. Weitere Informationen dazu finden Sie unter Verwenden von Snowflake Scripting in Snowflake CLI, SnowSQL, Classic Console und im Python-Connector.
Rufen Sie calculate_profit
in einer Abfrage auf:
SELECT calculate_profit(100, 110);
+----------------------------+
| CALCULATE_PROFIT(100, 110) |
|----------------------------|
| 10.00 |
+----------------------------+
Sie können das gleiche Snowflake Scripting-UDF verwenden und Spalten für die Argumente angeben. Erstellen Sie zunächst eine Tabelle und fügen Sie Daten ein:
CREATE OR REPLACE TABLE snowflake_scripting_udf_profit(
cost NUMBER(38, 2),
revenue NUMBER(38, 2));
INSERT INTO snowflake_scripting_udf_profit VALUES
(100, 200),
(200, 190),
(300, 500),
(400, 401);
Rufen Sie calculate_profit
in einer Abfrage auf und geben die Spalten für die Argumente an:
SELECT calculate_profit(cost, revenue)
FROM snowflake_scripting_udf_profit;
+---------------------------------+
| CALCULATE_PROFIT(COST, REVENUE) |
|---------------------------------|
| 100.00 |
| -10.00 |
| 200.00 |
| 1.00 |
+---------------------------------+
Erstellen einer Snowflake Scripting-UDF mit bedingter Logik¶
Erstellen Sie eine Snowflake Scripting-UDF, die mit einer bedingte Logik den Abteilungsnamen auf der Grundlage eines eingegebenen INTEGER-Werts bestimmt:
CREATE OR REPLACE function check_dept(department_id INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
BEGIN
IF (department_id < 3) THEN
RETURN 'Engineering';
ELSEIF (department_id = 3) THEN
RETURN 'Tool Design';
ELSE
RETURN 'Marketing';
END IF;
END;
Bemerkung
Wenn Sie Snowflake-CLI, SnowSQL und |sf-legacy-interface-link|oder die Methode execute_stream
oder execute_string
in Python-Konnektor-Code verwenden, müssen an diesem Beispiel geringfügige Änderungen vorgenommen werden. Weitere Informationen dazu finden Sie unter Verwenden von Snowflake Scripting in Snowflake CLI, SnowSQL, Classic Console und im Python-Connector.
Rufen Sie check_dept
in einer Abfrage auf:
SELECT check_dept(2);
+---------------+
| CHECK_DEPT(2) |
|---------------|
| Engineering |
+---------------+
Sie können eine SQL-Variable in einem Argument verwenden, wenn Sie eine Snowflake Scripting-UDF aufrufen. Das folgende Beispiel setzt eine SQL-Variable und verwendet diese Variable dann in einem Aufruf der check_dept
-UDF:
SET my_variable = 3;
SELECT check_dept($my_variable);
+--------------------------+
| CHECK_DEPT($MY_VARIABLE) |
|--------------------------|
| Tool Design |
+--------------------------+
Erstellen einer Snowflake Scripting-UDF mit einer Schleife¶
Erstellen Sie ein Snowflake Scripting-UDF, die mit einer Schleife alle Zahlen bis zu einer in einem Argument angegebenen Zielzahl zählt und die Summe aller gezählten Zahlen berechnet:
CREATE OR REPLACE function count_to(
target_number INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
DECLARE
counter INTEGER DEFAULT 0;
sum_total INTEGER DEFAULT 0;
BEGIN
WHILE (counter < target_number) DO
counter := counter + 1;
sum_total := sum_total + counter;
END WHILE;
RETURN 'Counted to ' || counter || '. Sum of all numbers: ' || sum_total;
END;
Bemerkung
Wenn Sie Snowflake-CLI, SnowSQL und |sf-legacy-interface-link|oder die Methode execute_stream
oder execute_string
in Python-Konnektor-Code verwenden, müssen an diesem Beispiel geringfügige Änderungen vorgenommen werden. Weitere Informationen dazu finden Sie unter Verwenden von Snowflake Scripting in Snowflake CLI, SnowSQL, Classic Console und im Python-Connector.
Rufen Sie count_to
in einer Abfrage auf:
SELECT count_to(10);
+---------------------------------------+
| COUNT_TO(10) |
|---------------------------------------|
| Counted to 10. Sum of all numbers: 55 |
+---------------------------------------+
Erstellen einer Snowflake Scripting-UDF mit Ausnahmebehandlung¶
Erstellen Sie eine Snowflake Scripting-UDF, die eine Ausnahme deklariert und dann die Ausnahme auslöst:
CREATE OR REPLACE FUNCTION raise_exception(input_value INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
DECLARE
counter_val INTEGER DEFAULT 0;
my_exception EXCEPTION (-20002, 'My exception text');
BEGIN
WHILE (counter_val < 12) DO
counter_val := counter_val + 1;
IF (counter_val > 10) THEN
RAISE my_exception;
END IF;
END WHILE;
RETURN counter_val;
EXCEPTION
WHEN my_exception THEN
IF (input_value = 1) THEN
RETURN 'My exception caught: ' || sqlcode;
ELSEIF (input_value = 2) THEN
RETURN 'My exception caught with different path: ' || sqlcode;
END IF;
RETURN 'Default exception handling path: ' || sqlcode;
END;
Bemerkung
Wenn Sie Snowflake-CLI, SnowSQL und |sf-legacy-interface-link|oder die Methode execute_stream
oder execute_string
in Python-Konnektor-Code verwenden, müssen an diesem Beispiel geringfügige Änderungen vorgenommen werden. Weitere Informationen dazu finden Sie unter Verwenden von Snowflake Scripting in Snowflake CLI, SnowSQL, Classic Console und im Python-Connector.
Rufen Sie raise_exception
in einer Abfrage auf, und geben Sie 1
als Eingabewert ein:
SELECT raise_exception(1);
+-----------------------------+
| RAISE_EXCEPTION(1) |
|-----------------------------|
| My exception caught: -20002 |
+-----------------------------+
Rufen Sie raise_exception
in einer Abfrage auf, und geben Sie 2
als Eingabewert ein:
SELECT raise_exception(2);
+-------------------------------------------------+
| RAISE_EXCEPTION(2) |
|-------------------------------------------------|
| My exception caught with different path: -20002 |
+-------------------------------------------------+t
Rufen Sie raise_exception
in einer Abfrage auf, und geben Sie NULL
als Eingabewert ein:
SELECT raise_exception(NULL);
+-----------------------------------------+
| RAISE_EXCEPTION(NULL) |
|-----------------------------------------|
| Default exception handling path: -20002 |
+-----------------------------------------+
Erstellen einer Snowflake Scripting-UDF, die einen Wert für eine INSERT-Anweisung zurückgibt¶
Erstellen Sie eine Snowflake Scripting-UDF, die einen Wert zurückgibt, der in einer INSERT-Anweisung verwendet wird. Erstellen Sie die Tabelle, in die die Werte eingefügt werden:
CREATE OR REPLACE TABLE test_sql_udf_insert (num NUMBER);
Erstellen Sie eine SQL-UDF, die einen numerischen Wert zurückgibt:
CREATE OR REPLACE FUNCTION value_to_insert(l NUMBER, r NUMBER)
RETURNS number
LANGUAGE SQL
AS
BEGIN
IF (r < 0) THEN
RETURN l/r * -1;
ELSEIF (r > 0) THEN
RETURN l/r;
ELSE
RETURN 0;
END IF;
END;
Bemerkung
Wenn Sie Snowflake-CLI, SnowSQL und |sf-legacy-interface-link|oder die Methode execute_stream
oder execute_string
in Python-Konnektor-Code verwenden, müssen an diesem Beispiel geringfügige Änderungen vorgenommen werden. Weitere Informationen dazu finden Sie unter Verwenden von Snowflake Scripting in Snowflake CLI, SnowSQL, Classic Console und im Python-Connector.
Rufen Sie value_to_insert
in mehreren INSERT-Anweisungen auf:
INSERT INTO test_sql_udf_insert SELECT value_to_insert(10, 2);
INSERT INTO test_sql_udf_insert SELECT value_to_insert(10, -2);
INSERT INTO test_sql_udf_insert SELECT value_to_insert(10, 0);
Fragen Sie die Tabelle ab, um die eingefügten Werte anzuzeigen:
SELECT * FROM test_sql_udf_insert;
+-----+
| NUM |
|-----|
| 5 |
| 5 |
| 0 |
+-----+
Erstellen einer Snowflake Scripting-UDF, die in WHERE- und ORDER BY-Klauseln aufgerufen wird¶
Erstellen Sie eine Snowflake Scripting-UDF, die einen Wert zurückgibt, der in einer WHERE- oder ORDER BY-Klausel verwendet wird. Erstellen Sie eine Tabelle, und fügen Sie Zeilen ein:
CREATE OR REPLACE TABLE test_sql_udf_clauses (p1 INT, p2 INT);
INSERT INTO test_sql_udf_clauses VALUES
(100, 7),
(100, 3),
(100, 4),
(NULL, NULL);
Erstellen Sie eine SQL-UDF, die einen numerischen Wert zurückgibt, der das Produkt der Multiplikation von zwei Eingabewerten ist:
CREATE OR REPLACE FUNCTION get_product(a INTEGER, b INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
BEGIN
RETURN a * b;
END;
Bemerkung
Wenn Sie Snowflake-CLI, SnowSQL und |sf-legacy-interface-link|oder die Methode execute_stream
oder execute_string
in Python-Konnektor-Code verwenden, müssen an diesem Beispiel geringfügige Änderungen vorgenommen werden. Weitere Informationen dazu finden Sie unter Verwenden von Snowflake Scripting in Snowflake CLI, SnowSQL, Classic Console und im Python-Connector.
Rufen Sie get_product
in der WHERE-Klausel einer Abfrage auf, um die Zeilen zurückzugeben, in denen das Produkt größer als 350
ist:
SELECT *
FROM test_sql_udf_clauses
WHERE get_product(p1, p2) > 350;
+-----+----+
| P1 | P2 |
|-----+----|
| 100 | 7 |
| 100 | 4 |
+-----+----+
Rufen Sie get_product
in der ORDER BY-Klausel einer Abfrage auf, um die Ergebnisse vom niedrigsten zum höchsten von der UDF zurückgegebenen Produkt zu ordnen:
SELECT *
FROM test_sql_udf_clauses
ORDER BY get_product(p1, p2);
+------+------+
| P1 | P2 |
|------+------|
| 100 | 3 |
| 100 | 4 |
| 100 | 7 |
| NULL | NULL |
+------+------+