CALL (匿名プロシージャの場合)

ストアドプロシージャ に似ていますが、後で使用するために保存されない匿名プロシージャを作成して呼び出します。

このコマンドでは、 WITH 句のパラメーターで定義された匿名プロシージャを作成し、そのプロシージャを呼び出します。

このコマンドには、 CREATE PROCEDURE スキーマ権限を持つロールは必要ありません。

プロシージャは 呼び出し元の権限 で実行されます。つまり、プロシージャは、呼び出し元の権限で実行され、現在のセッションコンテキストを使用し、呼び出し元のセッション変数とパラメーターにアクセスできます。

こちらもご参照ください。

CREATE PROCEDURECALL

構文

Javaおよび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> , ... ] )

Java および 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 } } ]
  [ , <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

インラインプロシージャの場合は、次の構文を使用します。

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> , ... ] )

コードがステージ上のファイルにあるプロシージャの場合は、次の構文を使用します。

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> , ... ] )

必須パラメーター

すべての言語

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

プロシージャの識別子(name)と入力引数を指定します。

RETURNS result_data_type [ [ NOT ] NULL ]

プロシージャによって返される結果の型を指定します。

NOT NULL を使用して、プロシージャはnull以外の値のみを返す必要があることを指定します。デフォルトは NULL です。これは、プロシージャが NULL を返すことができることを意味します。

実際問題として、呼び出しは式の一部とすることはできないため、戻り値は使用できません。

LANGUAGE language

プロシージャのハンドラーコードの言語を指定します。

現在、 language でサポートされている値は次のとおりです。

AS procedure_definition

プロシージャによって実行されるコードを定義します。定義は、任意の有効なコードで構成できます。

次の点に注意してください。

  • コードがインラインではないプロシージャの場合は、 AS 句を省略します。これには、Snowpark ScalaJava でプリコンパイル済みのプロシージャ、および コードがステージにあるPythonのプロシージャ が含まれます。

    代わりに IMPORTS 句を使用して、プロシージャのコードを含むファイルの場所を指定します。詳細については、以下をご参照ください。

  • procedure definition の前後に 文字列リテラル区切り文字' または $$)を使用する必要があります。

  • JavaScript のプロシージャで、改行を含む文字列を記述している場合は、文字列の前後にバッククォート(別称「バックティック」)を使用できます。

    次の JavaScript プロシージャの例では、プロシージャの本文に一重引用符と二重引用符が含まれているため、 $$ とバッククォートを使用しています。

    WITH proc3 AS PROCEDURE ()
      RETURNS VARCHAR
      LANGUAGE javascript
      AS
      $$
      var rs = snowflake.execute( { sqlText:
          `INSERT INTO table1 ("column 1")
              SELECT 'value 1' AS "column 1" ;`
          } );
      return 'Done.';
      $$
    CALL proc3();
    
  • Snowflakeはハンドラーコードを検証しません。ただし、ハンドラーコードが無効な場合にコマンドを実行すると、エラーが発生します。

ストアドプロシージャの詳細については、 ストアドプロシージャの使用 をご参照ください。

Java、Python、またはScala

RUNTIME_VERSION = 'language_runtime_version'

使用する言語ランタイムバージョン。サポートされているバージョンは次のとおりです。

  • Java: 11

  • Python: 3.8

  • Scala: 2.12

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

ハンドラーコードの実行環境に含める必要があるSnowflakeに展開された、パッケージの名前のコンマ区切りリスト。Snowparkパッケージはプロシージャに必要なため、常に PACKAGES 句で参照する必要があります。Snowparkの詳細については、 Snowpark API をご参照ください。

Snowflakeがプロシージャを実行する環境には、サポートされている言語用に選択されたパッケージのセットがデフォルトで含まれています。PACKAGES 句でこれらのパッケージを参照する場合、パッケージはSnowflakeですでに利用可能であるため、 IMPORTS 句でパッケージを含むファイルを参照する必要はありません。

指定の言語用にサポートされているパッケージとバージョンのリストについては、 INFORMATION_SCHEMA.PACKAGES ビュー でその言語をクエリして指定します。例:

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

ここで、 languagejavapython、または scala です。

PACKAGES 句でパッケージを参照するための構文は、以下で説明するように、パッケージの言語によって異なります。

  • Java

    次の形式を使用して、パッケージ名とバージョン番号を指定します。

    domain:package_name:version
    

    最新バージョンを指定するには、 latest に対して version を指定します。

    たとえば、Snowflakeにある最新のSnowparkライブラリのパッケージを含めるには、次を使用します。

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

    Snowparkライブラリからのパッケージを指定する場合は、バージョン1.3.0以降を指定する必要があります。

  • Python

    Snowflakeには、Anacondaから入手できる多数のパッケージが含まれています。詳細については、 サードパーティパッケージの使用 をご参照ください。

    次の形式を使用して、パッケージ名とバージョン番号を指定します。

    package_name[==version]
    

    最新バージョンを指定する場合は、バージョン番号を省略します。

    たとえば、spacyパッケージバージョン2.3.5を(必要なSnowparkパッケージの最新バージョンとともに)含めるには、次を使用します。

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

    Snowparkライブラリからのパッケージを指定する場合は、バージョン0.4.0以降を指定する必要があります。Snowflakeで利用可能な最新バージョンを使用するには、バージョン番号を省略します。

  • Scala

    次の形式を使用して、パッケージ名とバージョン番号を指定します。

    domain:package_name:version
    

    最新バージョンを指定するには、 latest に対して version を指定します。

    たとえば、Snowflakeにある最新のSnowparkライブラリのパッケージを含めるには、次を使用します。

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

    Snowflakeは、ScalaプロシージャでのSnowparkバージョン0.9.0以降の使用をサポートしています。ただし、これらのバージョンには制限があることに注意してください。たとえば、1.1.0より前のバージョンは、プロシージャでのトランザクションの使用をサポートしていません。

HANDLER = 'fully_qualified_method_name'

  • Python

    プロシージャの関数またはメソッドの名前を使用します。これは、コードがインラインであるか、ステージで参照されているかによって異なります。

    • コードがインラインの場合、次の例のように、関数名だけを指定できます。

      WITH myproc AS PROCEDURE()
        ...
        HANDLER = 'run'
        AS
        $$
        def run(session):
          ...
        $$
      CALL myproc();
      
    • コードをステージからインポートする場合は、完全修飾ハンドラー関数名を <モジュール名>.<関数名> として指定します。

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

    プロシージャのメソッドまたは関数の完全修飾名を使用します。これは通常、次の形式です。

    com.my_company.my_package.MyClass.myMethod
    

    条件:

    com.my_company.my_package
    

    オブジェクトまたはクラスを含むパッケージに対応します。

    package com.my_company.my_package;
    

オプションのパラメーター

すべての言語

CALLED ON NULL INPUT または . RETURNS NULL ON NULL INPUT | STRICT

null入力で呼び出されたときのプロシージャの動作を指定します。入力がnullの場合は常にnullを返すシステム定義関数とは対照的に、プロシージャはnull入力を処理でき、入力がnullの場合でもnull以外の値を返します。

  • CALLED ON NULL INPUT は、null入力で常にプロシージャを呼び出します。そのような値を適切に処理するのは手順次第です。

  • RETURNS NULL ON NULL INPUT (またはその同義語 STRICT)は、入力がnullの場合にプロシージャを呼び出さないため、プロシージャ内のステートメントは実行されません。代わりに、null値が常に返されます。プロシージャは、null以外の入力に対してもnullを返す場合があります。

デフォルト: CALLED ON NULL INPUT

Java、Python、またはScala

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

インポートするファイルの場所(ステージ)、パス、および名前。プロシージャが依存するファイルを含めるには、 IMPORTS 句を設定する必要があります。

  • インラインプロシージャを作成している場合は、コードがプロシージャまたはリソースファイルの外部で定義されたクラスに依存している場合を除き、この句を省略できます。

  • JavaまたはScala: プリコンパイル済みのプロシージャを記述する場合は、プロシージャの定義を含む JAR ファイルも含める必要があります。

  • Python: プロシージャのコードがステージ上にある場合は、コードが含まれているモジュールファイルへのパスも含める必要があります。

IMPORTS 句の各ファイルは、ファイルが異なるサブディレクトリまたは異なるステージにある場合でも、一意の名前を持っている必要があります。

使用上の注意

一般的な使用法

  • プロシージャはアトミックではありません。プロシージャ内の1つのステートメントが失敗した場合、プロシージャ内の他のステートメントは必ずしもロールバックされるとは限りません。ストアドプロシージャとトランザクションについては、 トランザクション管理 をご参照ください。

  • プロシージャは、文字列(例: 成功/失敗インジケーター)や数値(例: エラーコード)などの単一の値のみを返すことができます。より広範な情報を返す必要がある場合は、区切り文字(コンマなど)で区切られた値を含む VARCHAR、または VARIANT などの半構造化データ型を返すことができます。

  • メタデータについて、

    注意

    Snowflakeサービスを使用する場合、お客様は、個人データ(ユーザーオブジェクト向け以外)、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。

構文

  • WITH 句が SELECT ステートメントで使用される場合と同様に、 CALL ステートメントで使用される WITH 句は、プロシージャ定義に加えて、コンマで区切られた複数の CTEs の指定をサポートします。ただし、 WITH 句によって生成された表形式の値を CALL 句に渡すことはできません。

    ただし、 WITH 句で値が代入される単純な変数を指定することは可能です。

  • CALL 句は、構文の最後にする必要があります。

権限

  • このコマンドでプロシージャを作成して呼び出すには、 CREATE PROCEDURE スキーマ権限を持つロールは必要ありません。

  • プロシージャのハンドラーコードは、このコマンドを実行したユーザーに割り当てられたロールに許可されたアクションのみを実行できます。

言語固有

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

プロシージャの例については、 ストアドプロシージャの使用 をご参照ください。

最上部に戻る