EXECUTE IMMEDIATE FROM¶

EXECUTE IMMEDIATE FROM は、ステージ内のファイルで指定された SQL ステートメントを実行します。ファイルには SQL ステートメントまたは Snowflakeスクリプトブロックを含めることができます。ステートメントは構文的に正しい SQL ステートメントにする必要があります。

EXECUTE IMMEDIATE FROM コマンドを使用すると、どのSnowflakeセッションからでもファイル内のステートメントを実行できます。

この機能は、Snowflakeオブジェクトとコードの展開と管理を制御するメカニズムを提供します。たとえば、ストアドスクリプトを実行して、すべてのアカウントに標準のSnowflake環境を作成することができます。構成スクリプトには、新しいアカウントごとにユーザー、ロール、データベース、スキーマを作成するステートメントが含まれる場合があります。

Jinja2テンプレート化¶

EXECUTE IMMEDIATE FROM は、Jinja2テンプレート化言語を使ってテンプレートファイルを実行することもできます。テンプレートには変数や式を含めることができ、ループや条件分岐、変数の置換、マクロなどを使用することができます。テンプレートには、他のテンプレートを含めることもでき、ステージングされた他のファイルで定義されたマクロをインポートすることもできます。

テンプレート化言語の詳細については、 Jinja2ドキュメントをご参照ください。

実行するファイルは以下の条件を満たす必要があります。

構文的に有効なJinja2テンプレートであること。
ステージまたは Gitリポジトリのクローンにあります。
構文的に有効な SQL ステートメントをレンダリングできること。

テンプレート化によって、より柔軟な制御構造と、環境変数を使用したパラメーター化を実現できます。たとえば、テンプレートを使用して、スクリプトで定義したオブジェクトの展開ターゲットを動的に選択することができます。SQL スクリプトをレンダリングするためにテンプレートを使用するには、テンプレートディレクティブを使用するか、少なくとも1つのテンプレート変数を持つ USING 句を追加します。

テンプレート化ディレクティブ¶

2つのテンプレートディレクティブのいずれかを使うことができます。

推奨ディレクティブは SQL の有効な構文を使います。

--!jinja

オプションで、代替ディレクティブを使うこともできます。

#!jinja

注釈

ディレクティブの前には、バイトオーダーマークと最大10文字までの空白文字（改行、タブ、スペース）のみを配置することができます。ディレクティブの後に続く文字は無視されます。

ステージングされたファイルのコンテンツをテンプレートで使用する方法¶

テンプレートは SnowflakeFile API から直接、またはJinja2の include、 import、および inheritance 機能を使って他のステージングされたファイルをロードできます。

ファイルは絶対パスで参照できます。

{% include "@my_stage/path/to/my_template" %}
{% import "@my_stage/path/to/my_template" as my_template %}
{% extends "@my_stage/path/to/my_template" %}
{{ SnowflakeFile.open("@my_stage/path/to/my_template", 'r', require_scoped_url = False).read() }}

インクルード、インポート、エクステンドは相対パスもサポートし、 SnowflakeFile API はスコープされたSnowflakeファイル URLs をサポートします。

{% include "my_template" %}
{% import "../my_template" as my_template %}
{% extends "/path/to/my_template" %}

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

構文¶

EXECUTE IMMEDIATE
  FROM { absoluteFilePath | relativeFilePath }
  [ USING ( <key> => <value> [ , <key> => <value> [ , ... ] ]  )  ]
  [ DRY_RUN = { TRUE | FALSE } ]

条件:

absoluteFilePath ::=
   @[ <namespace>. ]<stage_name>/<path>/<filename>
relativeFilePath ::=
  '[ / | ./ | ../ ]<path>/<filename>'

必須パラメーター¶

絶対ファイルパス（`absoluteFilePath`）¶

namespace: 内部ステージまたは外部ステージが存在するデータベースまたはスキーマ、あるいはその両方で、 database_name.schema_name または schema_name の形式です。データベースとスキーマがユーザーセッション内で現在使用されている場合、名前空間はオプションです。それ以外の場合は必須です。
stage_name: 内部または外部ステージの名前。
path: ステージ内にある、大文字と小文字を区別したファイルへのパス。
filename: 実行するファイルの名前。構文的に正しく、有効な SQL ステートメントが含まれている必要があります。各ステートメントはコンマで区切る必要があります。

相対ファイルパス（`relativeFilePath`）¶

path: ステージ内にある、大文字と小文字を区別したファイルへの相対パス。相対パスは、先頭の / でステージのファイルシステムのルートを示し、 ./ で現在のディレクトリ（親ファイルがあるディレクトリ）を参照し、 ../ で親ディレクトリを参照するなど、確立された規則をサポートします。詳細については、使用上の注意をご参照ください。
filename: 実行するファイルの名前。構文的に正しく、有効な SQL ステートメントが含まれている必要があります。各ステートメントはコンマで区切る必要があります。

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

USING ( <key> => <value> [ , <key> => <value> [ , ... ] ] )

テンプレート展開のパラメーターとして使用できる、1つ以上のキーと値のペアを渡すことができます。キーと値のペアはコンマ区切りのリストを形成する必要があります。

USING 句がある場合、ファイルは SQL スクリプトとして実行される前に、まず Jinja2テンプレートとしてレンダリングされます。

条件:

key はテンプレート変数の名前です。テンプレート変数名は、オプションで二重引用符（"）で囲むことができます。

value はテンプレートの変数に割り当てる値です。文字列値は ' または $$ で囲む必要があります。例については、テンプレート化の使用上の注意をご参照ください。

DRY_RUN = { TRUE | FALSE }

SQL スクリプトとして実行せずに、レンダリングファイルをプレビューするかどうかを指定します。

TRUE は、 SQL ステートメントを実行せずに、レンダリングされたファイルのコンテンツを返します。
FALSE は、テンプレートから SQL ステートメントをレンダリングし、それらのステートメントを実行します。

デフォルト: FALSE

戻り値¶

EXECUTE IMMEDIATE FROM は次を返します。

すべてのステートメントが正常に実行された場合の、ファイルにある最後のステートメントの結果。
ファイル内のステートメントが失敗した場合のエラーメッセージ。

ファイル内のステートメントにエラーがある場合、 EXECUTE IMMEDIATE FROM コマンドは失敗し、失敗したステートメントのエラーメッセージが返されます。

注釈

EXECUTE IMMEDIATE FROM コマンドが失敗してエラーメッセージを返した場合、ファイル内の失敗したステートメントより前のステートメントは正常に完了しています。

アクセス制御の要件¶

EXECUTE IMMEDIATE FROM コマンドの実行に使用されるロールには、ファイルがあるステージに対する USAGE （外部ステージ）または READ （内部ステージ）権限が必要です。

ファイルの実行に使用されるロールは、そのロールが権限を持つファイル内のステートメントのみを実行することができます。たとえば、ファイル内に CREATE TABLE ステートメントがある場合、ロールにはアカウントにテーブルを作成するための必要な権限が求められます。必要な権限がないと、ステートメントは失敗します。

スキーマ内のオブジェクトを操作するには、親データベースの少なくとも1つの権限と、親スキーマの少なくとも1つの権限が必要です。

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

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

使用上の注意¶

実行されるファイルの SQL ステートメントには、 EXECUTE IMMEDIATE FROM ステートメントを含めることができます。
- ネストされた EXECUTE IMMEDIATE FROM ステートメントでは、相対ファイルパスを 使用できます。
  
  相対パスは、親ファイルのステージとファイルパスを基準に評価されます。相対ファイルパスが / で始まる場合、パスは親ファイルを含むステージのルートディレクトリから始まります。
  
  例については、例をご参照ください。
- 相対ファイルパスは、一重引用符（'）または $$ で囲む必要があります。
- ネストされたファイルの最大実行深度は5です。
絶対ファイルパスは、オプションで一重引用符（'）または $$ で囲むことができます。
実行するファイルのサイズは 10MB を超過することはできません。
実行するファイルは UTF-8 でエンコードする必要があります。
実行するファイルは解凍されている必要があります。PUT コマンドを使用して内部ステージにファイルをアップロードする場合は、 AUTO_COMPRESS パラメーターを明示的に FALSE に設定する必要があります。

たとえば、 my_file.sql を my_stage にアップロードします。
```
PUT file://~/sql/scripts/my_file.sql @my_stage/scripts/
  AUTO_COMPRESS=FALSE;
```
ディレクトリ内の全ファイルの実行はサポートされていません。例えば、 EXECUTE IMMEDIATE FROM @stage_name/scripts/ はエラーになります。

テンプレート化の使用上の注意¶

テンプレート内の変数名は大文字と小文字を区別します。
オプションで、テンプレート変数名を二重引用符で囲むことができます。予約キーワードが変数名として使われている場合は、変数名を囲むと便利です。
USING 句では、以下のパラメーター型がサポートされています。
- 文字列。' または $$ で囲む必要があります。例: USING (a => 'a', b => $$b$$)。
- 数値（10進数および整数）。例: USING (a => 1, b => -1.23)。
- ブール値。例: USING (a => TRUE, b => FALSE)。
- NULL。例: USING (a => NULL)。
  
  注釈
  
  Jinja2テンプレート化エンジンは NULL の値をPython NoneType の型として解釈します。
- セッション変数。例: USING (a => $var)。サポートされているデータ型の値を保持するセッション変数のみが許可されます。
- バインド変数。例: USING (a => :var)。サポートされているデータ型の値を保持するバインド変数のみが許可されます。バインド変数を使用して、ストアドプロシージャの引数をテンプレートに渡すことができます。
Snowflake GitリポジトリやSnowflake Native Apps内のファイルには、テンプレートからアクセスできません。
現在、テンプレートレンダリングの最大結果サイズは 100.000 バイトです。
テンプレートはJinja2バージョン3.1.6のテンプレート化エンジンを使ってレンダリングされます。