EXECUTE NOTEBOOK PROJECT

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

  • SQLファイル

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

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

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

重要

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

See also: CREATE NOTEBOOK PROJECT, CREATE TASK, CI/CD workflow scenario, ワークスペースにおけるノートブックの可観測性とログ, パラメーター付きノートブックの実行, Using secrets in Notebooks in Workspaces

構文

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> [ , ... ] ) ]
  [ SECRETS = ( <database_name>.<schema_name>.<secret_name> [ , ... ] ) ];

必須パラメーター

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

import sys
print(sys.argv)
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);

注釈

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

SECRETS = ( database_name.schema_name.secret_name [ , ... ] )

Optionally lists one or more secrets that the notebook may read during execution (for example, API keys or OAuth tokens referenced from Snowpark or mounted files).

Each entry must be a fully qualified secret name. Include this parameter (together with EXTERNAL_ACCESS_INTEGRATIONS) when the notebook performs authenticated outbound access that relies on secrets attached to the notebook service in Snowsight.

For setup, UI scheduling, and Python examples, see Using secrets in Notebooks in Workspaces.

アクセス制御の要件

:code:`EXECUTE NOTEBOOK PROJECT`を実行するロールは、ノートブックプロジェクトオブジェクト（NPO）に対するOWNERSHIP権限またはUSAGE権限のいずれかを持っている必要があります。

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

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

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

  • Tasks, external access integrations, and secrets referenced by the command.

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

セキュリティ保護可能なオブジェクト に対して 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')
  SECRETS = (sales_detection_db.schema.my_api_secret);