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:

Snowflake Scripting-UDFs unterstützen die folgenden Datentypen nur für Eingabeargumente:

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:

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;
Copy

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);
Copy
+----------------------------+
| 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);
Copy

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;
Copy
+---------------------------------+
| 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;
Copy

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);
Copy
+---------------+
| 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);
Copy
+--------------------------+
| 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;
Copy

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);
Copy
+---------------------------------------+
| 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;
Copy

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);
Copy
+-----------------------------+
| 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);
Copy
+-------------------------------------------------+
| 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);
Copy
+-----------------------------------------+
| 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);
Copy

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;
Copy

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

Fragen Sie die Tabelle ab, um die eingefügten Werte anzuzeigen:

SELECT * FROM test_sql_udf_insert;
Copy
+-----+
| 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);
Copy

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;
Copy

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;
Copy
+-----+----+
|  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);
Copy
+------+------+
|  P1  | P2   |
|------+------|
| 100  | 3    |
| 100  | 4    |
| 100  | 7    |
| NULL | NULL |
+------+------+