EXECUTE NOTEBOOK PROJECT

ノートブックプロジェクト（NPO）に保存されたノートブックを実行します。このコマンドは非インタラクティブ（ヘッドレス）モードでノートブックを実行し、CI/CDパイプラインやその他のオーケストレーションされたワークフローで、パラメーターを渡したり、依存関係のバージョンをロックしたりして、繰り返し実行できるようにするのに役立ちます。コマンドは以下から実行できます。

  • SQLファイル

  • その他のSnowflake実行可能ファイル（タスク）。

  • SQL を発行する外部オーケストレーション（例:Airflow、Prefect、Dagster、 CI/CD システム）。

コマンドは、構成したランタイム、コンピューティングプール、ウェアハウス、外部アクセス統合を使用する MAIN_FILE として指定したノートブックファイルを実行します。

重要

非インタラクティブな実行をトリガーする前に、ノートブックが実行コンテキスト（データベースとスキーマ）を設定しているか、完全修飾オブジェクト名を使用していることを確認してください。詳細については、 ワークスペースでのノートブックの編集と実行 をご参照ください。

以下もご参照ください。CREATE NOTEBOOK PROJECT、CREATE TASK、CI/CDワークフローシナリオ、ワークスペースにおけるノートブックの可観測性とログ、パラメーター付きノートブックの実行

構文

EXECUTE NOTEBOOK PROJECT <database_name>.<schema_name>.<project_name>
  MAIN_FILE = 'notebook.ipynb'
  COMPUTE_POOL = '<compute_pool_name>'
  QUERY_WAREHOUSE = '<warehouse_name>'
  RUNTIME = '<runtime_version>'
  [ ARGUMENTS = '<parameter_string>' ]
  [ REQUIREMENTS_FILE = '<path/to/requirements.txt>' ]
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <integration_name> [ , ... ] ) ];
Copy

必須パラメーター

database_name.schema_name.project_name

実行するノートブックプロジェクトの完全修飾識別子。

CREATE NOTEBOOK PROJECT で作成された既存のノートブックプロジェクトを参照する必要があります。

現在の DATABASE および SCHEMA に存在しない限り、完全修飾する必要があります。

詳細については、 識別子の要件 をご参照ください。

MAIN_FILE = 'notebook_file_name.ipynb'

実行するワークスペース内のメインノートブックファイルを指定します（path/to/notebook.ipynb）。

プロジェクトによって参照されるワークスペースにある .ipynb ノートブックファイルである必要があります。

パスはワークスペースルートからの相対パスです。

COMPUTE_POOL = 'compute_pool_name'

Container Runtime上でノートブックを実行するときに使用するコンピューティングプールを指定します。

ノートブックのランタイムが Snowpark Container Services を使用する場合は必須です。

QUERY_WAREHOUSE = 'warehouse_name'

SQL の実行とノートブックからのSnowparkクエリに使用される仮想ウェアハウスを指定します。

ノートブックが SQL またはSnowpark操作を実行する場合は必要で、ウェアハウスはそれ以外は構成されていません。

コンテナランタイムを使用する場合、ウェアハウスはクエリプッシュダウンを処理します。Pythonはコンピューティングプール上で実行されます。

RUNTIME = 'runtime_version'

ノートブックを実行するためのランタイムイメージ/バージョンを指定します（例: '1.0' or '2.2-CPU-PY3.11' ）。

ノートブックの実行に使用するPythonのバージョンと実行環境を決定します。

Container Runtime イメージ（ CPU または GPU ）またはウェアハウスランタイムバリアントに対応します。

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

プロジェクトとランタイムの構成方法に応じて、次のパラメーターを設定する必要がある場合があります。以下の説明は、その目的と一般的な使用法を定義しています。

ARGUMENTS = 'parameter_string'

オプションで、実行時にノートブックに sys.argv リストでコマンドライン引数として表示される1つ以上の文字列引数を渡します。引数は、ノートブックのロジックを動的にするのに便利です（たとえば、 env prod などの環境を選択する場合）。

複数の引数を渡すには、スペースで区切られた単一の文字列で指定します。引数は区切り文字として空白を使用して sys.argv に分解されます。Pythonのセルでは、 sys.argv[0] を使ってノートブック名の引数に、 sys.argv[1] を使って最初の引数にアクセスするなどします。

文字列のみがサポートされています。他のデータ型（整数やブール値など）はNULLとして解釈されます。

例：

ARGUMENTS = 'env prod';
Copy
import sys
print(sys.argv)
Copy
REQUIREMENTS_FILE = '<path/to/requirements.txt>'

オプションでワークスペースまたはステージ上の requirements.txt ファイルを指定し、ノートブックの実行前にライブラリ（pandasやscikit-learnなど）やその他のPythonの依存関係の正確なバージョンをプリインストールします。依存関係のピン留めはべき等性にとって重要であり、ノートブックの実行をより再現性のあるものにし、ライブラリのバージョンの変更に起因するエラーを減らすのに役立ちます。ファイルは、実行ロールがアクセスできる必要があります。

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

実行中にノートブックが使用できる1つ以上の外部アクセス統合を指定します。

ノートブックがアウトバウンドネットワーク呼び出し（たとえば、外部 APIs ）を行う場合に必要です。

各統合名は、既存の外部アクセス統合を参照する必要があります。

複数の外部アクセス統合は、括弧内のコンマ区切りのリストで指定できます。

例:

EXTERNAL_ACCESS_INTEGRATIONS = (http_eai, s3_eai);
Copy

注釈

Snowflake管理のPyPIネットワークルール SNOWFLAKE.EXTERNAL_ACCESS.PYPI_RULE には、ACCOUNTADMINロールのみがアクセスできます。その結果、ノートブックオブジェクトやスケジュールされたタスクに対してこのルールを外部アクセス統合（EAI）で使用すると、失敗する可能性があります。これを回避するには、PyPI用ユーザー定義のネットワークルールを作成し、外部アクセス統合で参照します。詳細については、 Snowflake管理のエグレスネットワークルール をご参照ください。

アクセス制御の要件

EXECUTE NOTEBOOK PROJECT を実行するロールにはノートブックプロジェクトに対して十分な権限が必要です。

さらに、実行ロールはクエリウェアハウスに対するUSAGEおよびMONITOR、ならびに以下に対するUSAGEまたはOWNERSHIPを持つ必要があります。

  • コンピューティングプール。

  • ノートブックプロジェクトを含むデータベースとスキーマ。

  • コマンドによって参照されるタスクと外部アクセス統合。

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

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

使用上の注意

  • ノートブックからEXECUTE NOTEBOOK PROJECTコマンドは使用できません。

  • タスクから EXECUTE NOTEBOOK PROJECT を呼び出すことができるため、より大きなワークフローの一部としてノートブックを実行できるようにします。

  • Snowflakeは、 EXECUTE AS USER 句を使用して実行するよう構成されているタスクに EXECUTE NOTEBOOK PROJECT コマンドを埋め込むことをサポートしていません。このようなタスクを作成するとエラーメッセージは表示されませんが、タスクが実行されると失敗します。

  • EXECUTE NOTEBOOK PROJECT コマンドを使用してノートブックを実行する場合。

  • ノートブックコードは、RUNTIMEパラメーターで指定されたランタイムを使用するCOMPUTE_POOLで指定されたコンピューティングプール上で実行されます。

  • SQLとSnowparkのクエリは、QUERY_WAREHOUSEパラメーターで指定されたウェアハウスを使用して実行されます。

例

ノートブックプロジェクトを実行します。

EXECUTE NOTEBOOK PROJECT "sales_detection_db"."schema"."DEFAULT_PROJ_B32BCFD4"
  MAIN_FILE = 'notebook_file.ipynb'
  COMPUTE_POOL = 'test_X_CPU'
  QUERY_WAREHOUSE = 'ENG_INFRA_WH'
  RUNTIME = 'V2.2-CPU-PY3.10'
  ARGUMENTS = 'env prod'
  REQUIREMENTS_FILE = 'path/to/requirements.txt'
  EXTERNAL_ACCESS_INTEGRATIONS = ('test_EAI');
Copy