CREATE PROCEDURE

新しい ストアドプロシージャ を作成します。

プロシージャは、次のいずれかの言語で記述できます。

注釈

匿名の(格納されているのではなく)プロシージャを作成して呼び出す場合は、 CALL (匿名プロシージャでの場合) を使用します。匿名プロシージャの作成には、 CREATE PROCEDURE スキーマ権限を持つロールは必要ありません。

このコマンドは次のバリアントをサポートしています。

  • CREATE OR ALTER PROCEDURE: プロシージャが存在しない場合は新規に作成し、存在する場合は既存のプロシージャを変更します。

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

ALTER PROCEDUREDROP PROCEDURESHOW PROCEDURESDESCRIBE PROCEDURECALL

CREATE OR ALTER <オブジェクト>

構文

Javaハンドラー

インラインのハンドラーコードを含めるか、 JAR ファイル内のハンドラーコードを参照して、ストアドプロシージャを作成できます。詳細については、 ハンドラーコードのインラインまたはステージ上での保持 をご参照ください。

Javaストアドプロシージャの例については、 SQL で作成されたストアドプロシージャの Java ハンドラーを記述します。 をご参照ください。

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

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  LANGUAGE JAVA
  RUNTIME_VERSION = '<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>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ TARGET_PATH = '<stage_path_and_file_name_to_write>' ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { OWNER | CALLER | RESTRICTED CALLER } ]
  AS '<procedure_definition>'
Copy

プリコンパイル済みハンドラーを使用するストアドプロシージャの場合は、次の構文を使用します。

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  LANGUAGE JAVA
  RUNTIME_VERSION = '<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>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ VOLATILE | IMMUTABLE ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { OWNER | CALLER | RESTRICTED CALLER } ]
Copy

JavaScript ハンドラー

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

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS <result_data_type> [ NOT NULL ]
  LANGUAGE JAVASCRIPT
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ VOLATILE | IMMUTABLE ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { OWNER | CALLER | RESTRICTED CALLER } ]
  AS '<procedure_definition>'
Copy

重要

JavaScript は大文字と小文字を区別しますが、 SQL は区別しません。JavaScriptコードでストアドプロシージャの引数名を使用する際の重要な情報については、 JavaScript 引数の大文字と小文字の区別 をご参照ください。

Pythonハンドラー

Pythonストアドプロシージャの例については、 SQL と Python を使ったストアドプロシージャの記述 をご参照ください。

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

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  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>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { OWNER | CALLER | RESTRICTED CALLER }]
  AS '<procedure_definition>'
Copy

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

CREATE [ OR REPLACE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  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>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { OWNER | CALLER | RESTRICTED CALLER } ]
Copy

Scalaハンドラー

インラインのハンドラーコードを含めるか、 JAR ファイル内のハンドラーコードを参照して、ストアドプロシージャを作成できます。詳細については、 ハンドラーコードのインラインまたはステージ上での保持 をご参照ください。

Scalaストアドプロシージャの例については、 SQL で作成したストアドプロシージャの Scala ハンドラーを記述します。 をご参照ください。

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

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  LANGUAGE SCALA
  RUNTIME_VERSION = '<scala_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>'
  [ TARGET_PATH = '<stage_path_and_file_name_to_write>' ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { OWNER | CALLER | RESTRICTED CALLER } ]
  AS '<procedure_definition>'
Copy

プリコンパイル済みハンドラーを使用するストアドプロシージャの場合は、次の構文を使用します。

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  LANGUAGE SCALA
  RUNTIME_VERSION = '<scala_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 } } ]
  [ VOLATILE | IMMUTABLE ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { OWNER | CALLER | RESTRICTED CALLER } ]
Copy

Snowflakeスクリプトハンドラー

Snowflakeスクリプトストアドプロシージャの例については、 Snowflakeスクリプトでのストアドプロシージャの記述 をご参照ください。

CREATE [ OR REPLACE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  [ NOT NULL ]
  LANGUAGE SQL
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { OWNER | CALLER | RESTRICTED CALLER } ]
  AS <procedure_definition>
Copy

注釈

SnowSQL または Classic Console でSnowflakeスクリプトプロシージャを作成する場合は、 procedure definition の前後に 文字列リテラル区切り文字' または $$)を使用する必要があります。 SnowSQL、 Classic Console、Python ConnectorでSnowflakeスクリプトを使用する をご参照ください。

バリアント構文

CREATE OR ALTER PROCEDURE

プロシージャがまだ存在しない場合は新規に作成し、存在する場合は既存のプロシージャをステートメントで定義されたプロシージャに変換します。CREATE OR ALTER PROCEDURE ステートメントは、 CREATE PROCEDURE ステートメントの構文ルールに従い、このステートメントには ALTER PROCEDURE ステートメントと同じ制限があります。

以下の変更をサポートしています。

  • LOG_LEVEL, TRACE_LEVEL, COMMENT, SECURE

  • Python、Scala、およびJavaストアドプロシージャの SECRETS および EXTERNAL_ACCESS_INTEGRATIONS

  • 実行権限(EXECUTE AS CALLER または EXECUTE AS OWNER)

詳細については、 CREATE OR ALTER PROCEDURE の使用上の注意 をご参照ください。

CREATE [ OR ALTER ] PROCEDURE ...
Copy

必須パラメーター

すべての言語

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

ストアドプロシージャのために識別子(name)、入力引数、およびオプション引数のデフォルト値を指定します。

  • 識別子用:

    • ストアドプロシージャは、 名前と引数の型の組み合わせによって識別および解決される ため、識別子は、プロシージャが作成されるスキーマに対して一意である必要はありません。

    • 識別子はアルファベットで始まる必要があり、識別子の文字列全体が二重引用符で囲まれている場合を除き、スペースや特殊文字を含めることはできません(例:"私のオブジェクト")。二重引用符で囲まれた識別子も大文字と小文字が区別されます。 識別子の要件 をご参照ください。

  • 入力引数の場合、

    • arg_name には、入力引数の名前を指定します。

    • arg_data_type には、使用している言語に対応するSnowflakeデータ型を使用します。

      注釈

      Java、Python、またはScala(Snowpark APIsを使用)で作成するストアドプロシージャの場合、Snowpark Session オブジェクトの引数を省略します。

      Session 引数は、 CREATE PROCEDURE または CALL で指定する仮パラメーターではありません。ストアドプロシージャを呼び出すと、Snowflakeは自動的に Session オブジェクトを作成し、それをストアドプロシージャのハンドラー関数に渡します。

    • 引数が省略可能であることを示すには、 DEFAULT default_value を使用して引数のデフォルト値を指定します。デフォルト値には、リテラルまたは式を使用できます。

      オプションの引数を指定する場合は、必須引数の後に配置する必要があります。

      プロシージャにオプションの引数がある場合は、同じ名前で異なる署名を持つプロシージャを追加で定義することはできません。

      詳細については、 引数をオプションに指定する をご参照ください。

RETURNS result_data_type [ NOT NULL ]

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

  • result_data_type には、使用している言語の型に対応するSnowflakeデータ型を使用します。

    注釈

    Snowpark(JavaまたはScala)で作成するストアドプロシージャには、戻り値が必要です。Snowpark(Python)では、ストアドプロシージャが値を返さない場合、 None を返していると見なされます。プロシージャが明示的に何も返さない場合でも、すべての CREATE PROCEDURE ステートメントに戻り型を定義する RETURNS 句を含める必要があることに注意してください。

  • 返されたテーブルの列の Snowflakeデータ型 がわかっている場合、 RETURNS TABLE ( [ col_name col_data_type [ , ... ] ] ) には、列名と型を指定します。

    CREATE OR REPLACE PROCEDURE get_top_sales()
      RETURNS TABLE (sales_date DATE, quantity NUMBER)
    ...
    
    Copy

    それ以外の場合(実行時に列タイプを決定する場合など)は、列名と型を省略できます。

    CREATE OR REPLACE PROCEDURE get_top_sales()
      RETURNS TABLE ()
    
    Copy

    注釈

    現在、 RETURNS TABLE(...) 句では、 GEOGRAPHY を列タイプとして指定することはできません。これは、ストアドプロシージャまたは匿名プロシージャを作成する場合に適用されます。

    CREATE OR REPLACE PROCEDURE test_return_geography_table_1()
      RETURNS TABLE(g GEOGRAPHY)
      ...
    
    Copy
    WITH test_return_geography_table_1() AS PROCEDURE
      RETURNS TABLE(g GEOGRAPHY)
      ...
    CALL test_return_geography_table_1();
    
    Copy

    列タイプとして GEOGRAPHY を指定しようとすると、ストアドプロシージャの呼び出しはエラーになります。

    Stored procedure execution error: data type of returned table does not match expected returned table type
    
    Copy

    この問題を回避するには、 RETURNS TABLE() の列の引数と型を省略します。

    CREATE OR REPLACE PROCEDURE test_return_geography_table_1()
      RETURNS TABLE()
      ...
    
    Copy
    WITH test_return_geography_table_1() AS PROCEDURE
      RETURNS TABLE()
      ...
    CALL test_return_geography_table_1();
    
    Copy

    RETURNS TABLE は、ハンドラーが次の言語で記述されている場合にのみサポートされます。

実際問題として、 Snowflakeスクリプトのブロック 外では、 呼び出しは式の一部とすることはできないため、戻り値は使用できません

LANGUAGE language

ストアドプロシージャコードの言語を指定します。これは、 Snowflakeスクリプト で記述されたストアドプロシージャでは、オプションであることに注意してください。

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

デフォルト: SQL

AS procedure_definition

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

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

  • コードがインラインでないストアドプロシージャの場合は、AS句を省略します。これには、ステージングされたハンドラーを持つストアドプロシージャが含まれます。

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

    インラインハンドラーとステージングされたハンドラーの詳細については、 ハンドラーコードのインラインまたはステージ上での保持 をご参照ください。

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

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

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

    CREATE OR REPLACE TABLE table1 ("column 1" VARCHAR);
    
    Copy
    CREATE or replace PROCEDURE proc3()
      RETURNS VARCHAR
      LANGUAGE javascript
      AS
      $$
      var rs = snowflake.execute( { sqlText: 
          `INSERT INTO table1 ("column 1") 
               SELECT 'value 1' AS "column 1" ;`
           } );
      return 'Done.';
      $$;
    
    Copy
  • CREATE PROCEDURE コマンドを実行しても、Snowflakeはコードを包括的には検証しません。

    たとえば、Snowpark(Scala)ストアドプロシージャの場合、入力引数の数と型は検証されますが、関数の本文は検証されません。1つまたは複数の型が一致しない場合(例: 引数が非数値型のときにSnowflakeデータ型 NUMBER が使用されている場合)に、 CREATE PROCEDURE コマンドを実行するとエラーが発生します。

    コードが有効でない場合は、 CREATE PROCEDURE コマンドが成功し、ストアドプロシージャが呼び出されたときにエラーが返されます。

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

Java

RUNTIME_VERSION = 'language_runtime_version'

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

  • 11

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

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

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

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

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'java';
Copy

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

domain:package_name:version
Copy

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

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

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

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

HANDLER = 'fully_qualified_method_name'

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

com.my_company.my_package.MyClass.myMethod
Copy

条件:

com.my_company.my_package
Copy

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

package com.my_company.my_package;
Copy

Python

RUNTIME_VERSION = 'language_runtime_version'

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

  • 3.9

  • 3.10

  • 3.11

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

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

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

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

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'python';
Copy

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

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

package_name[==version]
Copy

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

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

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

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

HANDLER = 'fully_qualified_method_name'

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

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

    CREATE OR REPLACE PROCEDURE MYPROC(from_table STRING, to_table STRING, count INT)
      ...
      HANDLER = 'run'
    AS
    $$
    def run(session, from_table, to_table, count):
      ...
    $$;
    
    Copy
  • コードをステージからインポートする場合は、完全修飾ハンドラー関数名を <モジュール名>.<関数名> として指定します。

    CREATE OR REPLACE PROCEDURE MYPROC(from_table STRING, to_table STRING, count INT)
      ...
      IMPORTS = ('@mystage/my_py_file.py')
      HANDLER = 'my_py_file.run';
    
    Copy

Scala

RUNTIME_VERSION = 'language_runtime_version'

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

  • 2.12

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

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

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

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

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'scala';
Copy

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

domain:package_name:version
Copy

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

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

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

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

HANDLER = 'fully_qualified_method_name'

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

com.my_company.my_package.MyClass.myMethod
Copy

条件:

com.my_company.my_package
Copy

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

package com.my_company.my_package;
Copy

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

すべての言語

SECURE

プロシージャがセキュアであることを指定します。セキュアプロシージャの詳細については、 セキュア UDFs とストアドプロシージャの使用による機密情報の保護 をご参照ください。

[ [ NOT ] NULL ]

ストアドプロシージャにより NULL 値を返すことができるか、 NON-NULL 値のみを返す必要があるかを指定します。

デフォルトは NULL です(つまり、ストアドプロシージャは NULL を返すことができます)。

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

VOLATILE | IMMUTABLE

非推奨

注意

これらのキーワードは、ストアドプロシージャでは廃止されています。これらのキーワードは、ストアドプロシージャに適用することを目的としたものではありません。将来のリリースでは、これらのキーワードはドキュメントから削除される予定です。

COMMENT = 'string_literal'

SHOW PROCEDURES 出力の DESCRIPTION 列に表示されるストアドプロシージャのコメントを指定します。

デフォルト: stored procedure

EXECUTE AS OWNER または . EXECUTE AS CALLER または . EXECUTE AS RESTRICTED CALLER

ストアドプロシージャが、所有者の権限(「所有者の権利」ストアドプロシージャ)または呼び出し元の権限(「呼び出し元の権利」ストアドプロシージャ)で実行するかどうかを指定します。

  • CREATE PROCEDURE ... EXECUTE AS OWNER を実行すると、その後、プロシージャは所有者の権利プロシージャとして実行されます。

  • CREATE PROCEDURE ... EXECUTE AS CALLER ステートメントを実行すると、その後、プロシージャは呼び出し元の権限プロシージャとして実行されます。

  • ステートメント CREATE PROCEDURE ... EXECUTE AS RESTRICTED CALLER を実行すると、将来、プロシージャは呼び出し元権限のプロシージャとして実行されますが、呼び出し元のすべての権限で実行することはできない場合があります。詳細については、 制限された呼び出し元権限 をご参照ください。

EXECUTE AS ... が指定されていない場合、プロシージャは所有者権限のストアドプロシージャとして実行されます。所有者の権利のストアドプロシージャは、呼び出し側の環境(例: 呼び出し元のセッション変数)へのアクセスが少なく、Snowflakeはデフォルトでこの高いレベルのプライバシーとセキュリティを使用します。

詳細については、 呼び出し元権限と所有者権限のストアドプロシージャについて をご参照ください。

デフォルト: OWNER

COPY GRANTS

CREATE OR REPLACE PROCEDURE を使用して新しいプロシージャを作成するときに、元のプロシージャからのアクセス権限を保持することを指定します。

このパラメーターは、既存のプロシージャから新しいプロシージャに、 OWNERSHIP を 除く すべての権限をコピーします。新しいプロシージャは、スキーマ内のオブジェクト型に定義された将来の付与を継承します。デフォルトでは、 CREATE PROCEDURE ステートメントを実行するロールが新しいプロシージャを所有します。

ノート:

  • 置換プロシージャの SHOW GRANTS 出力には、ステートメントが実行されたときの現在のタイムスタンプとともに、コピーされた権限の被付与者が CREATE PROCEDURE ステートメントを実行したロールとしてリストされます。

  • 許可をコピーする操作は、CREATE PROCEDURE コマンドで(つまり、同じトランザクション内で)アトミックに発生します。

Java

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

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

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

  • ステージングされたハンドラーを使用してストアドプロシージャを記述する場合は、ストアドプロシージャのハンドラーコードを含む JAR ファイルへのパスも含める必要があります。

  • IMPORTS 定義は、ストアドプロシージャに渡される引数から変数を参照できません。

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

TARGET_PATH = stage_path_and_file_name_to_write

procedure_definition で指定されたハンドラーソースコードをコンパイルした結果を含んだ JAR ファイルを、Snowflakeが書き込む場所を指定します。

この句が含まれている場合、Snowflakeは結果の JAR ファイルを句の値で指定されたステージの場所に書き込みます。この句を省略すると、Snowflakeはコードが必要になるたびにソースコードを再コンパイルします。その場合、 JAR ファイルは永久に保存されず、ユーザーは JAR ファイルをクリーンアップする必要はありません。

TARGET_PATH が既存のファイルと一致する場合、Snowflakeはエラーを返します。 TARGET_PATH を使用して既存のファイルを上書きすることはできません。

IMPORTS 句と TARGET_PATH 句の両方を指定する場合は、ファイルが異なるサブディレクトリまたは異なるステージにあっても、 TARGET_PATH 句にあるファイル名と IMPORTS 句にある各ファイル名は異なる必要があります。

プロシージャをドロップしても、生成された JAR ファイルは明示的に削除されるまで残ります。JAR はプロシージャをサポートするには不要になったため、プロシージャをドロップする際には JAR ファイルを別途削除する必要があります。

たとえば、以下の TARGET_PATH の例では、 myhandler.jar ファイルが生成され、 handlers ステージにコピーされます。

TARGET_PATH = '@handlers/myhandler.jar'
Copy

このプロシージャをドロップして削除する場合は、 REMOVE コマンド を実行するなどして、そのハンドラー JAR ファイルも削除する必要があります。

REMOVE @handlers/myhandler.jar;
Copy
EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

このプロシージャのハンドラーコードが外部ネットワークにアクセスするために必要な 外部アクセス統合 の名前。

外部アクセス統合は、 ネットワークルールシークレット を指定します。これは、外部 REST API などの外部ネットワークをリクエストするときに、ハンドラーコードによって使用が許可される外部ロケーションと認証情報(ある場合)を指定します。

SECRETS = ( 'secret_variable_name' = secret_name [ , ...  ] )

シークレットの名前を変数に代入し、ハンドラーコードでシークレットから情報を取得する際に、変数を使用してシークレットを参照できるようにします。

ここで指定するシークレットは、この CREATE PROCEDURE コマンドの EXTERNAL_ACCESS_INTEGRATIONS パラメーター値として指定された 外部アクセス統合 によって許可されている必要があります。

このパラメーターの値は、次の部分からなる代入式のカンマ区切りのリストです。

  • secret_name を許可されたシークレットの名前として使用します。

    EXTERNAL_ACCESS_INTEGRATIONS パラメーターで指定された統合にもシークレットが含まれていない SECRETS 値を指定すると、エラーが発生します。

  • 'secret_variable_name' を、シークレットから情報を取得する際にハンドラーコードで使用する変数にします。

例などの詳細については、 関数またはプロシージャでの外部アクセス統合の使用 をご参照ください。

Python

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

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

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

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

  • IMPORTS 定義は、ストアドプロシージャに渡される引数から変数を参照できません。

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

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

このプロシージャのハンドラーコードが外部ネットワークにアクセスするために必要な 外部アクセス統合 の名前。

外部アクセス統合は、 ネットワークルールシークレット を指定します。これは、外部 REST API などの外部ネットワークをリクエストするときに、ハンドラーコードによって使用が許可される外部ロケーションと認証情報(ある場合)を指定します。

SECRETS = ( 'secret_variable_name' = secret_name [ , ...  ] )

シークレットの名前を変数に代入し、ハンドラーコードでシークレットから情報を取得する際に、変数を使用してシークレットを参照できるようにします。

ここで指定するシークレットは、この CREATE PROCEDURE コマンドの EXTERNAL_ACCESS_INTEGRATIONS パラメーター値として指定された 外部アクセス統合 によって許可されている必要があります。

このパラメーターの値は、次の部分からなる代入式のカンマ区切りのリストです。

  • secret_name を許可されたシークレットの名前として使用します。

    EXTERNAL_ACCESS_INTEGRATIONS パラメーターで指定された統合にもシークレットが含まれていない SECRETS 値を指定すると、エラーが発生します。

  • 'secret_variable_name' を、シークレットから情報を取得する際にハンドラーコードで使用する変数にします。

例などの詳細については、 関数またはプロシージャでの外部アクセス統合の使用 をご参照ください。

Scala

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

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

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

  • ステージングされたハンドラーを使用してストアドプロシージャを記述する場合は、ストアドプロシージャのハンドラーコードを含む JAR ファイルへのパスも含める必要があります。

  • IMPORTS 定義は、ストアドプロシージャに渡される引数から変数を参照できません。

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

TARGET_PATH = stage_path_and_file_name_to_write

procedure_definition で指定されたハンドラーソースコードをコンパイルした結果を含んだ JAR ファイルを、Snowflakeが書き込む場所を指定します。

この句が含まれている場合、Snowflakeは結果の JAR ファイルを句の値で指定されたステージの場所に書き込みます。この句を省略すると、Snowflakeはコードが必要になるたびにソースコードを再コンパイルします。その場合、 JAR ファイルは永久に保存されず、ユーザーは JAR ファイルをクリーンアップする必要はありません。

TARGET_PATH が既存のファイルと一致する場合、Snowflakeはエラーを返します。 TARGET_PATH を使用して既存のファイルを上書きすることはできません。

IMPORTS 句と TARGET_PATH 句の両方を指定する場合は、ファイルが異なるサブディレクトリまたは異なるステージにあっても、 TARGET_PATH 句にあるファイル名と IMPORTS 句にある各ファイル名は異なる必要があります。

プロシージャをドロップしても、生成された JAR ファイルは明示的に削除されるまで残ります。JAR はプロシージャをサポートするには不要になったため、プロシージャをドロップする際には JAR ファイルを別途削除する必要があります。

たとえば、以下の TARGET_PATH の例では、 myhandler.jar ファイルが生成され、 handlers ステージにコピーされます。

TARGET_PATH = '@handlers/myhandler.jar'
Copy

このプロシージャをドロップして削除する場合は、 REMOVE コマンド を実行するなどして、そのハンドラー JAR ファイルも削除する必要があります。

REMOVE @handlers/myhandler.jar;
Copy

アクセス制御の要件

この操作の実行に使用される ロール には、少なくとも次の 権限 が必要です。

権限

オブジェクト

メモ

CREATE PROCEDURE

スキーマ

USAGE

プロシージャ

新しく作成されたプロシージャの USAGE 権限をロールに付与すると、そのロールを持つユーザーは、Snowflakeの他の場所でそのプロシージャを呼び出すことができます。

USAGE

外部アクセス統合

プロシージャの作成時に指定された統合がある場合は、統合に必要です。詳細については、 CREATE EXTERNAL ACCESS INTEGRATION をご参照ください。

READ

シークレット

プロシージャを作成する際に指定されたシークレットがある場合は、シークレットに必要です。詳細については、 認証情報を表すシークレットの作成 および 関数またはプロシージャでの外部アクセス統合の使用 をご参照ください。

USAGE

スキーマ

プロシージャの作成時に指定されたシークレットがある場合は、それを含むスキーマに必要です。詳細については、 認証情報を表すシークレットの作成 および 関数またはプロシージャでの外部アクセス統合の使用 をご参照ください。

スキーマ内のオブジェクトに対して操作を実行するには、親データベースとスキーマに対する USAGE 権限が必要です。

指定された権限のセットを使用してカスタムロールを作成する手順については、 カスタムロールの作成 をご参照ください。

セキュリティ保護可能なオブジェクト に対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、 アクセス制御の概要 をご参照ください。

一般的な使用上の注意

CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。

その他の使用上の注意については、以下をご参照ください。

すべてのハンドラー言語

  • ストアドプロシージャは オーバーロード をサポートします。2つのプロシージャは、パラメーターの数またはパラメーターのデータ型が異なる場合、同じ名前を持つことができます。

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

  • メタデータについて:

    注意

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

Tip

組織が呼び出し元の権利と所有者の権利のストアドプロシージャを組み合わせて使用している場合は、ストアドプロシージャの命名規則を使用して、個々のストアドプロシージャが呼び出し元の権利のストアドプロシージャか、所有者の権利のストアドプロシージャかを示すことができます。

Java

既知の制限事項 をご参照ください。

Javascript

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

Python

既知の制限事項 をご参照ください。

Scala

既知の制限事項 をご参照ください。

CREATE OR ALTER PROCEDURE の使用上の注意

これにより、ハードコードされた値を返す簡単なストアドプロシージャが作成されます。これは非現実的ですが、最小限の JavaScript コードで基本的な SQL 構文を示しています。

CREATE OR REPLACE PROCEDURE sp_pi()
    RETURNS FLOAT NOT NULL
    LANGUAGE JAVASCRIPT
    AS
    $$
    return 3.1415926;
    $$
    ;
Copy

これは、 JavaScript API への呼び出しを含むより現実的な例を示しています。このプロシージャのより広範なバージョンでは、ユーザーが直接挿入する権限を持っていないテーブルにデータを挿入できます。JavaScript ステートメントは、特定の要件が満たされた場合にのみ、入力パラメーターをチェックし、 SQL INSERT を実行できます。

CREATE OR REPLACE PROCEDURE stproc1(FLOAT_PARAM1 FLOAT)
    RETURNS STRING
    LANGUAGE JAVASCRIPT
    STRICT
    EXECUTE AS OWNER
    AS
    $$
    var sql_command = 
     "INSERT INTO stproc_test_table1 (num_col1) VALUES (" + FLOAT_PARAM1 + ")";
    try {
        snowflake.execute (
            {sqlText: sql_command}
            );
        return "Succeeded.";   // Return a success/error indicator.
        }
    catch (err)  {
        return "Failed: " + err;   // Return a success/error indicator.
        }
    $$
    ;
Copy

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

インラインハンドラー

次の例のコードは、Pythonインラインハンドラー関数 run を使用して my_proc というプロシージャを作成します。コードは、 PACKAGES 句を介して、含まれているPython用のSnowparkライブラリを参照します。Pythonがプロシージャハンドラー言語である場合は、その Session が必要です。

CREATE OR REPLACE PROCEDURE my_proc(from_table STRING, to_table STRING, count INT)
  RETURNS STRING
  LANGUAGE PYTHON
  RUNTIME_VERSION = '3.9'
  PACKAGES = ('snowflake-snowpark-python')
  HANDLER = 'run'
AS
$$
def run(session, from_table, to_table, count):
  session.table(from_table).limit(count).write.save_as_table(to_table)
  return "SUCCESS"
$$;
Copy

ステージングされたハンドラー

次の例のコードは、ステージングされたJavaハンドラーメソッド MyClass.myMethod を使用して my_proc というプロシージャを作成します。コードは、 PACKAGES 句を介して、含まれているJava用のSnowparkライブラリを参照します。Javaがプロシージャハンドラー言語である場合は、その Session が必要です。IMPORTS 句を使用すると、コードはハンドラーコードを含むステージングされた JAR ファイルを参照します。

CREATE OR REPLACE PROCEDURE my_proc(fromTable STRING, toTable STRING, count INT)
  RETURNS STRING
  LANGUAGE JAVA
  RUNTIME_VERSION = '11'
  PACKAGES = ('com.snowflake:snowpark:latest')
  IMPORTS = ('@mystage/myjar.jar')
  HANDLER = 'MyClass.myMethod';
Copy

CREATE OR ALTER PROCEDURE コマンドを使ってプロシージャを作成し、変更する

外部アクセス統合とデフォルトの OWNER 権限を持っている所有者権限のPythonストアドプロシージャを作成します。

CREATE OR ALTER PROCEDURE python_add1(A NUMBER)
  RETURNS NUMBER
  LANGUAGE PYTHON
  HANDLER='main'
  RUNTIME_VERSION=3.10
  EXTERNAL_ACCESS_INTEGRATIONS=(example_integration)
  PACKAGES = ('snowflake-snowpark-python')
  EXECUTE AS OWNER
  AS
$$
def main(session, a):
    return a+1
$$;
Copy

ストアドプロシージャのシークレットを変更し、ストアドプロシージャを呼び出し元権限のプロシージャに変更します。

CREATE OR ALTER PROCEDURE python_add1(A NUMBER)
  RETURNS NUMBER
  LANGUAGE PYTHON
  HANDLER='main'
  RUNTIME_VERSION=3.10
  EXTERNAL_ACCESS_INTEGRATIONS=(example_integration)
  secrets=('secret_variable_name'=secret_name)
  PACKAGES = ('snowflake-snowpark-python')
  EXECUTE AS CALLER
  AS
$$
def main(session, a):
    return a+1
$$;
Copy