EXECUTE NOTEBOOK PROJECT

노트북 프로젝트(NPO)에 저장된 노트북을 실행하는 명령이에요. 노트북을 비대화형(headless) 모드로 실행하며, CI/CD 파이프라인이나 매개변수를 전달하거나 재현 가능한 실행을 위해 의존성 버전을 고정하고 싶은 오케스트레이션 워크플로에 유용해요.

출처: 문서

본문

참고: Notebook Project 객체는 Code Bundle로 이름이 바뀌었어요. 이 페이지의 NOTEBOOK PROJECT 문법은 기존 태스크와 일정을 포함하여 계속 동작해요. 현재 명령과 새로운 기능은 EXECUTE CODE BUNDLE과 Snowflake Code Bundles를 참조해요.

이 명령은 다음에서 실행할 수 있어요:

SQL 파일
다른 Snowflake 실행 가능 객체(태스크)
SQL을 발행하는 외부 오케스트레이터(예: Airflow, Prefect, Dagster, CI/CD 시스템)

명령은 구성한 런타임, 컴퓨팅 풀, 웨어하우스, 외부 액세스 통합을 사용하여 MAIN_FILE로 지정한 노트북 파일을 실행해요.

중요: 비대화형 실행을 트리거하기 전에 노트북이 실행 컨텍스트(데이터베이스와 스키마)를 설정하거나 정규화된 객체 이름을 사용하는지 확인해요.

구문 (Syntax)

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 = ( '<arg>' [ , '<arg>' ... ] ) ]
  [ REQUIREMENTS_FILE = '<path/to/requirements.txt>' ]
  [ ARTIFACT_REPOSITORIES = ( <repo_name> [ , ... ] ) ]
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <integration_name> [ , ... ] ) ]
  [ SECRETS = ( <database_name.schema_name.secret_name> [ , ... ] ) ];

필수 파라미터 (Required parameters)

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' 또는 '2.2-CPU-PY3.11'). 노트북 실행에 사용되는 Python 버전과 실행 환경을 결정해요. Container Runtime 이미지(CPU 또는 GPU) 또는 웨어하우스 런타임 변형에 해당해요.

선택 파라미터 (Optional parameters)

프로젝트와 런타임이 구성된 방식에 따라 다음 파라미터를 설정해야 할 수 있어요.

ARGUMENTS = ( 'arg' [ , 'arg' ... ] ) — 실행 시점에 노트북에 하나 이상의 문자열 인자를 선택적으로 전달해요. 이 인자는 sys.argv 목록의 명령줄 인자로 나타나요. 인자는 노트북 로직을 동적으로 만드는 데 유용해요(예: --env prod 같은 환경 선택). 각 인자를 목록에서 별도의 따옴표 문자열로 지정해요. Python 셀에서 sys.argv[0](노트북 이름), sys.argv[1](첫 번째 인자) 등으로 인자에 접근해요. 문자열만 지원되며, 다른 데이터 유형(정수, 부울 등)은 NULL로 해석돼요.

ARGUMENTS = ('--env', 'prod');

import sys
print(sys.argv)

REQUIREMENTS_FILE = '<path/to/requirements.txt>' — 노트북 실행 전에 정확한 라이브러리 버전(pandas, scikit-learn 등)과 기타 Python 의존성을 사전 설치하기 위해 워크스페이스 또는 스테이지의 requirements.txt 파일을 선택적으로 지정해요. 의존성 고정은 멱등성에 중요하며, 라이브러리 버전 변경으로 인한 오류를 줄여 노트북 실행을 더 반복 가능하게 만드는 데 도움이 돼요. 파일은 실행 역할이 접근할 수 있어야 해요.
EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] ) — 노트북이 실행 중에 사용할 수 있는 하나 이상의 외부 액세스 통합을 지정해요. 노트북이 아웃바운드 네트워크 호출(예: 외부 API)을 할 때 필요해요. 각 통합 이름은 기존 외부 액세스 통합을 참조해야 해요. 괄호 안에 쉼표로 구분된 목록으로 여러 외부 액세스 통합을 지정할 수 있어요.

EXTERNAL_ACCESS_INTEGRATIONS = (http_eai, s3_eai);

참고: Snowflake 관리 PyPI 네트워크 규칙 SNOWFLAKE.EXTERNAL_ACCESS.PYPI_RULE은 ACCOUNTADMIN 역할만 접근할 수 있어요. 따라서 이 규칙을 노트북 객체나 예약된 태스크의 외부 액세스 통합(EAI)에서 사용하면 실패할 수 있어요. 이를 피하려면 PyPI용 사용자 정의 네트워크 규칙을 만들고 외부 액세스 통합에서 그 규칙을 참조해요.

SECRETS = ( database_name.schema_name.secret_name [ , ... ] ) — 노트북이 실행 중에 읽을 수 있는 하나 이상의 시크릿을 선택적으로 나열해요(예: Snowpark 또는 마운트된 파일에서 참조되는 API 키 또는 OAuth 토큰). 각 항목은 정규화된 시크릿 이름이어야 해요. 노트북이 Snowsight에서 노트북 서비스에 연결된 시크릿에 의존하는 인증된 아웃바운드 접근을 수행할 때 이 파라미터를 (EXTERNAL_ACCESS_INTEGRATIONS와 함께) 포함해요.

접근 제어 요구사항 (Access control requirements)

EXECUTE NOTEBOOK PROJECT를 실행하는 역할은 노트북 프로젝트 객체(NPO)에 대해 OWNERSHIP 또는 USAGE 권한이 있어야 해요.

또한 실행 역할은 쿼리 웨어하우스에 대한 USAGE와 MONITOR, 그리고 다음에 대한 USAGE 또는 OWNERSHIP이 있어야 해요:

컴퓨팅 풀.
노트북 프로젝트를 포함하는 데이터베이스와 스키마.
명령이 참조하는 태스크, 외부 액세스 통합, 시크릿.

사용 메모 (Usage notes)

노트북에서 EXECUTE NOTEBOOK PROJECT 명령을 사용할 수 없어요.
태스크에서 EXECUTE NOTEBOOK PROJECT를 호출하여 더 큰 워크플로의 일부로 노트북 실행을 가능하게 할 수 있어요.
이 명령으로 트리거된 실행의 실행 기록 및 실행 결과 가시성은 조회 역할의 NPO 권한과 시작 사용자에 대한 IMPERSONATE 권한에 따라 달라져요.
EXECUTE NOTEBOOK PROJECT 명령으로 노트북을 실행할 때:
- 노트북 코드는 RUNTIME 파라미터가 지정한 런타임을 사용하여 COMPUTE_POOL 파라미터가 지정한 컴퓨팅 풀에서 실행돼요.
- SQL 및 Snowpark 쿼리는 QUERY_WAREHOUSE 파라미터가 지정한 웨어하우스를 사용하여 실행돼요.

예시 (Examples)

노트북 프로젝트를 실행해요:

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.9-CPU-PY3.12'
  ARGUMENTS = ('--env', 'prod')
  REQUIREMENTS_FILE = 'path/to/requirements.txt'
  ARTIFACT_REPOSITORIES = (snowflake.snowpark.pypi_shared_repository)
  EXTERNAL_ACCESS_INTEGRATIONS = ('test_EAI')
  SECRETS = (sales_detection_db.schema.my_api_secret);

더 알아보기 (Learn more)

본문