CALL (mit anonymen Prozeduren)

Ermöglicht das Erstellen und Aufrufen einer anonymen Prozedur, die wie eine gespeicherte Prozedur ist, aber nicht zur späteren Verwendung gespeichert wird.

Mit diesem Befehl erstellen Sie eine anonyme Prozedur, die durch Parameter in der WITH-Klausel definiert ist, und rufen diese Prozedur auf.

Für diesen Befehl benötigen Sie keine Rolle mit CREATE PROCEDURE-Schemaberechtigungen.

Die Prozedur wird mit Aufruferrechten ausgeführt, was bedeutet, dass die Prozedur mit den Berechtigungen des Aufrufers ausgeführt wird, dass sie den aktuellen Sitzungskontext verwendet und Zugriff auf die Sitzungsvariablen und Parameter des Aufrufers hat.

Siehe auch:

CREATE PROCEDURE, CALL.

Syntax

Java und Scala

WITH <name> AS PROCEDURE ([ <arg_name> <arg_data_type> ]) [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE { SCALA | JAVA }
  RUNTIME_VERSION = '<scala_or_java_runtime_version>'
  PACKAGES = ( 'com.snowflake:snowpark:<version>' [, '<package_name_and_version>' ...] )
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [, '<stage_path_and_file_name_to_read>' ...] ) ]
  HANDLER = '<fully_qualified_method_name>'
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ AS '<procedure_definition>' ]
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
CALL <name> ( [ <arg> , ... ] )

Für vorkompilierte Prozeduren in Scala und Java verwenden Sie die folgende Syntax:

WITH <name> AS PROCEDURE ([ <arg_name> <arg_data_type> ]) [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE { SCALA | JAVA }
  RUNTIME_VERSION = '<scala_or_java_runtime_version>'
  PACKAGES = ( 'com.snowflake:snowpark:<version>' [, '<package_name_and_version>' ...] )
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [, '<stage_path_and_file_name_to_read>' ...] ) ]
  HANDLER = '<fully_qualified_method_name>'
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
CALL <name> ( [ <arg> , ... ] )

JavaScript

WITH <name> AS PROCEDURE ([ <arg_name> <arg_data_type> ]) [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE JAVASCRIPT
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  AS '<procedure_definition>'
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
CALL <name> ( [ <arg> , ... ] )

Python

Für Inline-Prozeduren verwenden Sie die folgende Syntax:

WITH <name> AS PROCEDURE ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE PYTHON
  RUNTIME_VERSION = '<python_version>'
  PACKAGES = ( 'snowflake-snowpark-python[==<version>]'[, '<package_name>[==<version>]' ... ])
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [, '<stage_path_and_file_name_to_read>' ...] ) ]
  HANDLER = '<function_name>'
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
  AS '<procedure_definition>'
CALL <name> ( [ <arg> , ... ] )

Für eine Prozedur, bei der sich der Code in einer Datei in einem Stagingbereich befindet, verwenden Sie die folgende Syntax:

WITH <name> AS PROCEDURE ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE PYTHON
  RUNTIME_VERSION = '<python_version>'
  PACKAGES = ( 'snowflake-snowpark-python[==<version>]'[, '<package_name>[==<version>]' ... ])
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [, '<stage_path_and_file_name_to_read>' ...] ) ]
  HANDLER = '<module_file_name>.<function_name>'
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ , <name> AS PROCEDURE ([ <arg_name> <arg_data_type> ]) [ , ... ] ) ... ]
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
CALL <name> ( [ <arg> , ... ] )

Erforderliche Parameter

Alle Sprachen

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

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

RETURNS result_data_type [ [ NOT ] NULL ]

Gibt den von der Prozedur zurückgegebenen Ergebnistyp an.

Verwenden Sie NOT NULL, um anzugeben, dass die Prozedur nur Nicht-Null-Werte zurückgeben darf. Der Standardwert ist NULL, was bedeutet, dass die Prozedur NULL zurückgeben kann.

In der Praxis kann der zurückgegebene Wert nicht verwendet werden, da der Aufruf nicht Teil eines Ausdrucks sein kann.

LANGUAGE language

Gibt die Sprache des Handler-Codes der Prozedur an.

Derzeit werden folgende Werte für language (Sprache) unterstützt:

AS procedure_definition

Definiert den Code, der von der Prozedur ausgeführt wird. Die Definition kann aus jedem gültigen Code bestehen.

Beachten Sie Folgendes:

Weitere Informationen zu gespeicherten Prozeduren finden Sie unter Verwenden von gespeicherten Prozeduren.

Java, Python oder Scala

RUNTIME_VERSION = 'language_runtime_version'

Die zu verwendende Laufzeitversion der Programmiersprache. Folgende Versionen werden derzeit unterstützt:

  • Java: 11

  • Python: 3.8

  • Scala: 2.12

PACKAGES = ( 'snowpark_package_name' [, 'package_name' ...] )

Eine durch Komma getrennte Liste mit den Namen der in Snowflake bereitgestellten Pakete, die in die Ausführungsumgebung des Handler-Codes aufgenommen werden sollen. Das Snowpark-Paket ist für Prozeduren erforderlich und muss daher immer in der PACKAGES-Klausel referenziert werden. Weitere Informationen zu Snowpark finden Sie unter Snowpark-API.

Standardmäßig enthält die Umgebung, in der Snowflake Prozeduren ausführt, einen ausgewählten Satz von Paketen für unterstützte Sprachen. Wenn Sie in der PACKAGES-Klausel auf diese Pakete verweisen, ist es nicht erforderlich, in der IMPORTS-Klausel auf eine Datei zu verweisen, die das Paket enthält, da das Paket bereits in Snowflake verfügbar ist.

Eine Liste der unterstützten Pakete und Versionen erhalten Sie, indem Sie die Ansicht INFORMATION_SCHEMA.PACKAGES unter Angabe der Sprache abfragen. Beispiel:

select * from information_schema.packages where language = '<language>';

wobei language (Sprache) den Wert java, python oder scala hat.

Die Syntax für den Verweis auf ein Paket in der PACKAGES-Klausel variiert je nach der Sprache des Pakets, wie unten beschrieben.

  • Java

    Geben Sie den Paketnamen und die Versionsnummer in der folgenden Form an:

    domain:package_name:version
    

    Für die neueste Version geben Sie latest für version an.

    Um beispielsweise ein Paket aus der neuesten Snowpark-Bibliothek in Snowflake einzubinden, verwenden Sie Folgendes:

    PACKAGES = ('com.snowflake:snowpark:latest')
    

    Wenn Sie ein Paket aus der Snowpark-Bibliothek angeben, müssen Sie Version 1.3.0 oder höher angeben.

  • Python

    Snowflake enthält eine große Anzahl von Paketen, die über Anaconda verfügbar sind. Weitere Informationen dazu finden Sie unter Verwenden von Drittanbieter-Paketen.

    Geben Sie den Paketnamen und die Versionsnummer in der folgenden Form an:

    package_name[==version]
    

    Um die neueste Version anzugeben, lassen Sie die Versionsnummer weg.

    Um beispielsweise Version 2.3.5 des spacy-Pakets (zusammen mit der neuesten Version des erforderlichen Snowpark-Pakets) einzubinden, verwenden Sie Folgendes:

    PACKAGES = ('snowflake-snowpark-python', 'spacy==2.3.5')
    

    Wenn Sie ein Paket aus der Snowpark-Bibliothek angeben, müssen Sie Version 0.4.0 oder höher angeben. Lassen Sie die Versionsnummer weg, um die neueste in Snowflake verfügbare Version zu verwenden.

  • Scala

    Geben Sie den Paketnamen und die Versionsnummer in der folgenden Form an:

    domain:package_name:version
    

    Für die neueste Version geben Sie latest für version an.

    Um beispielsweise ein Paket aus der neuesten Snowpark-Bibliothek in Snowflake einzubinden, verwenden Sie Folgendes:

    PACKAGES = ('com.snowflake:snowpark:latest')
    

    Snowflake unterstützt die Verwendung von Snowpark, Version 0.9.0 oder höher in einer Scala-Prozedur. Beachten Sie jedoch, dass diese Versionen Einschränkungen haben. So unterstützen Versionen vor 1.1.0 beispielsweise nicht die Verwendung von Transaktionen in einer Prozedur.

HANDLER = 'fully_qualified_method_name'

  • Python

    Verwenden Sie den Namen der Funktion oder Methode der Prozedur. Dies kann unterschiedlich sein, je nachdem, ob der Code inline ist oder er in einem Stagingbereich referenziert wird.

    • Wenn der Code inline ist, können Sie nur den Funktionsnamen angeben, wie im folgenden Beispiel:

      WITH myproc AS PROCEDURE()
        ...
        HANDLER = 'run'
        AS
        $$
        def run(session):
          ...
        $$
      CALL myproc();
      
    • Wenn der Code aus einem Stagingbereich importiert wird, geben Sie den vollqualifizierten Namen der Handlerfunktion als <Name_des_Moduls>.<Name_der_Funktion> an.

      WITH myproc AS PROCEDURE()
        ...
        IMPORTS = ('@mystage/my_py_file.py')
        HANDLER = 'my_py_file.run'
      CALL myproc();
      
  • Java und Scala

    Verwenden Sie den vollqualifizierten Namen der Methode oder Funktion der Prozedur. Dies geschieht typischerweise in der folgenden Form:

    com.my_company.my_package.MyClass.myMethod
    

    Wobei:

    com.my_company.my_package
    

    entspricht dem Paket, das das Objekt oder die Klasse enthält:

    package com.my_company.my_package;
    

Optionale Parameter

Alle Sprachen

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

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

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

  • RETURNS NULL ON NULL INPUT (oder dessen Synonym STRICT) ruft die Prozedur nicht auf, wenn eine Eingabe Null ist, sodass die Anweisungen in der Prozedur nicht ausgeführt werden. Stattdessen wird immer ein Null-Wert zurückgegeben. Beachten Sie, dass die Prozedur bei Nicht-Null-Eingaben immer noch Null zurückgeben kann.

Standard: CALLED ON NULL INPUT

Java, Python oder Scala

IMPORTS = ( 'stage_path_and_file_name_to_read' [, 'stage_path_and_file_name_to_read' ...] )

Der Speicherort (Stagingbereich), der Pfad und der Name der zu importierenden Datei(en). Sie müssen die IMPORTS-Klausel festlegen, um alle Dateien einzuschließen, von denen Ihre Prozedur abhängt:

  • Wenn Sie eine Inline-Prozedur schreiben, können Sie diese Klausel weglassen, es sei denn, Ihr Code hängt von Klassen ab, die außerhalb der Prozedur oder der Ressourcendateien definiert sind.

  • Java oder Scala: Wenn Sie eine vorkompilierte Prozedur schreiben, müssen Sie auch die JAR-Datei angeben, die die Definition der Prozedur enthält.

  • Python: Wenn sich der Code Ihrer Prozedur in einem Stagingbereich befindet, müssen Sie auch einen Pfad zu der Moduldatei angeben, in der sich der Code befindet.

Jede Datei in der IMPORTS-Klausel muss einen eindeutigen Namen haben, auch wenn sich die Dateien in verschiedenen Unterverzeichnissen oder verschiedenen Stagingbereichen befinden.

Nutzungshinweise

Allgemeine Nutzung

  • Prozeduren sind nicht atomar. Wenn eine Anweisung in einer Prozedur fehlschlägt, werden die anderen Anweisungen in der Prozedur nicht unbedingt zurückgesetzt. Weitere Informationen zu Prozeduren und Transaktionen finden Sie unter Transaktionsmanagement.

  • Eine Prozedur kann nur einen einzigen Wert zurückgeben, z. B. eine Zeichenfolge (beispielsweise einen Erfolg/Fehler-Indikator) oder eine Zahl (z. B. einen Fehlercode). Wenn Sie umfangreichere Daten zurückgeben müssen, können Sie einen VARCHAR-Wert verwenden, der durch ein Trennzeichen (z. B. ein Komma) getrennte Werte enthält, oder Sie verwenden einen Datentyp für semistrukturierte Daten wie VARIANT.

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

Syntax

  • Ähnlich wie bei der Verwendung einer WITH-Klausel mit einer SELECT-Anweisung können bei der Verwendung einer WITH-Klausel mit CALL zusätzlich zur Prozedurdefinition mehrere durch Kommas getrennte CTEs angegeben werden. Es ist jedoch nicht möglich, tabellarische Werte, die durch eine WITH-Klausel erzeugt wurden, an die CALL-Klausel zu übergeben.

    Es ist jedoch möglich, eine einfache Variable anzugeben, deren Wert in der WITH-Klausel zugewiesen wird.

  • Die CALL-Klausel muss in der Syntax an letzter Stelle stehen.

Berechtigungen

  • Das Erstellen und Aufrufen einer Prozedur mit diesem Befehl erfordert keine Rolle mit CREATE PROCEDURE-Schemaberechtigungen.

  • Der Handler-Code der Prozedur kann nur Aktionen ausführen, die für die Rolle der Person, die diesen Befehl ausgeführt hat, zulässig sind.

Hinweise zu Programmiersprachen

Beispiele

with copy_to_table as procedure (fromTable string, toTable string, count int)
  returns string
  language scala
  packages = ('com.snowflake:snowpark:latest')
  handler = 'DataCopy.copyBetweenTables'
  as
  $$
    object DataCopy
    {
      def copyBetweenTables(session: com.snowflake.snowpark.Session, fromTable: String, toTable: String, count: Int): String =
      {
        session.table(fromTable).limit(count).write.saveAsTable(toTable)
        return "Success"
      }
    }
  $$
call copy_to_table('table_a', 'table_b', 5);

Weitere Beispiele für Prozeduren finden Sie unter Verwenden von gespeicherten Prozeduren.

Zurück zum Anfang