EXECUTE NOTEBOOK PROJECT

노트북 프로젝트(NPO)에 저장된 노트북을 실행합니다. 이 명령은 비대화형(헤드리스) 모드에서 노트북을 실행하며, 반복 가능한 실행을 위해 매개 변수를 전달하거나 종속성 버전을 잠그려는 CI/CD 파이프라인 및 기타 오케스트레이션 워크플로에 유용합니다. 명령은 다음에서 실행될 수 있습니다.

  • SQL 파일.

  • 기타 Snowflake 실행 파일(작업).

  • SQL을 발급하는 외부 오케스트레이터(예:Airflow, Prefect, Dagster, CI/CD시스템).

이 명령은 사용자가 구성한 런타임, 컴퓨팅 풀, 웨어하우스 및 외부 액세스 통합을 사용하여 사용자가 :code:`MAIN_FILE`로 지정한 노트북 파일을 실행합니다.

중요

비대화형 실행을 트리거하기 전에 노트북이 실행 컨텍스트(데이터베이스 및 스키마)를 설정하거나 정규화된 오브젝트 이름을 사용하는지 확인합니다. 자세한 내용은 :doc:`작업 공간에서 노트북 편집 및 실행하기 </user-guide/ui-snowsight/notebooks-in-workspaces/notebooks-in-workspaces-edit-run>`를 참조하세요.

CREATE NOTEBOOK PROJECT, CREATE TASK, CI 및 CD 워크플로 시나리오, 작업 공간의 Notebooks에 대한 가시성 및 로깅, 매개 변수로 노트북 실행 참조

구문

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

실행할 노트북 프로젝트의 정규화된 식별자입니다.

:doc:`CREATE NOTEBOOK PROJECT<create-notebook-project>`로 생성된 기존 노트북 프로젝트를 참조해야 합니다.

현재 DATABASE 및 SCHEMA에 상주하지 않는 한 정규화되어야 합니다.

자세한 내용은 식별자 요구 사항 섹션을 참조하십시오.

MAIN_FILE = 'notebook_file_name.ipynb'

실행할 작업 공간 내의 기본 노트북 파일을 지정합니다(path/to/notebook.ipynb).

프로젝트에서 참조하는 작업 공간에 있는 .ipynb 노트북 파일이어야 합니다.

경로는 작업 공간 루트를 기준으로 합니다.

COMPUTE_POOL = 'compute_pool_name'

Container Runtime에서 노트북을 실행할 때 사용되는 컴퓨팅 풀을 지정합니다.

노트북 런타임이 |spcs|를 사용할 때 필요합니다.

QUERY_WAREHOUSE = 'warehouse_name'

노트북에서 SQL 및 Snowpark 쿼리를 실행하는 데 사용되는 가상 웨어하우스를 지정합니다.

노트북이 SQL 또는 Snowpark 작업을 수행하는 경우 필요하며, 달리 구성된 웨어하우스가 없습니다.

Container Runtime을 사용할 때 웨어하우스는 쿼리 푸시다운을 처리하며, Python은 컴퓨팅 풀에서 실행됩니다.

RUNTIME = 'runtime_version'

노트북을 실행하기 위한 런타임 이미지/버전을 지정합니다(예: '1.0' or '2.2-CPU-PY3.11').

노트북 실행에 사용되는 Python 버전과 실행 환경을 결정합니다.

Container Runtime 이미지(CPU또는 GPU) 또는 Warehouse Runtime 베리언트에 해당합니다.

선택적 매개 변수

프로젝트 및 런타임 구성 방식에 따라 다음 매개 변수를 설정해야 할 수도 있습니다. 아래 설명은 그 목적과 일반적인 사용법을 정의합니다.

ARGUMENTS = 'parameter_string'

런타임 시 노트북에 하나 이상의 문자열 인자를 선택적으로 전달하며, 이는 sys.argv 목록에서 명령줄 인자로 표시됩니다. 인자는 노트북 논리를 동적으로 만드는 데 유용합니다(예: env prod 등의 환경 선택).

여러 인자를 전달하려면 공백으로 구분된 단일 문자열로 지정합니다. 인자는 공백을 구분 기호로 사용하여 :code:`sys.argv`로 구문 분석됩니다. Python 셀에서 노트북 이름에 :code:`sys.argv[0]`를 사용하고 첫 번째 인자에 :code:`sys.argv[1]`를 사용하는 식으로 인자에 액세스합니다.

문자열만 지원되며, 다른 데이터 타입(예: 정수 또는 부울)은 NULL로 해석됩니다.

예제:

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

선택적으로 노트북 실행 전에 정확한 버전의 라이브러리(예: pandas 또는 scikit-learn) 및 기타 Python 종속성을 사전 설치하기 위해 작업 공간 또는 스테이지에 requirements.txt 파일을 지정합니다. 종속성 고정은 멱등성에 매우 중요하며 노트북 실행을 더 반복 가능하게 만들어 라이브러리 버전 변경으로 인해 발생하는 오류를 줄이는 데 도움이 됩니다. 실행 중인 역할이 파일에 액세스할 수 있어야 합니다.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

노트북이 실행 중에 사용할 수 있는 하나 이상의 외부 액세스 통합을 지정합니다.

노트북이 아웃바운드 네트워크를 호출할 때 필요합니다(예: 외부 APIs).

각 통합 이름은 기존 외부 액세스 통합을 참조해야 합니다.

괄호 안의 쉼표로 구분된 목록으로 여러 외부 액세스 통합을 지정할 수 있습니다.

예:

EXTERNAL_ACCESS_INTEGRATIONS = (http_eai, s3_eai);
Copy

참고

Snowflake 관리 PyPI 네트워크 규칙:code:`SNOWFLAKE.EXTERNAL_ACCESS.PYPI_RULE`은 ACCOUNTADMIN 역할만 액세스할 수 있습니다. 따라서 노트북 오브젝트 또는 예약된 작업에 대한 외부 액세스 통합(EAI)에서 이 규칙을 사용하면 실패할 수 있습니다. 이를 방지하려면 PyPI에 대한 사용자 정의 네트워크 규칙을 생성하고 외부 액세스 통합에서 이를 참조합니다. 자세한 내용은 :ref:`Snowflake 관리 송신 네트워크 규칙 <label-snowflake_managed_egress_network_rules>`을 참조하세요.

액세스 제어 요구 사항

:code:`EXECUTE NOTEBOOK PROJECT`를 실행하는 역할에는 노트북 프로젝트에 대한 충분한 권한이 있어야 합니다.

또한, 실행 역할에는 쿼리 웨어하우스에 대한 USAGE 및 MONITOR 권한이나 다음에 대한 USAGE 또는 OWNERSHIP 권한이 있어야 합니다.

  • 컴퓨팅 풀.

  • 노트북 프로젝트가 포함된 데이터베이스 및 스키마.

  • 명령이 참조하는 작업 및 외부 액세스 통합.

지정된 권한 세트로 사용자 지정 역할을 만드는 방법에 대한 지침은 사용자 지정 역할 만들기 섹션을 참조하십시오.

보안 오브젝트 에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여에 대한 일반적인 정보는 액세스 제어의 개요 섹션을 참조하십시오.

사용법 노트

  • 노트북에서는 EXECUTE NOTEBOOK PROJECT 명령을 사용할 수 없습니다.

  • 작업에서 :code:`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