SQL 스크립트 및 노트북 예약

주의: Dataplex Explore는 지원 중단되어 2025년 7월 1일부터 더 이상 지원되지 않습니다. 모든 Google Cloud 분석 도구에서 간소화된 데이터 탐색 환경을 이용하려면 애셋을 BigQuery Studio로 전환하는 것이 좋습니다. Explore에서 BigQuery Studio로 마이그레이션을 참조하세요.

SQL 스크립트 및 노트북을 예약하면 Data Exploration Workbench(탐색)에서 만든 애셋을 운용할 수 있습니다.

SQL 스크립트 또는 노트북을 예약하면 미리 정해진 시간에 한 번 또는 반복적으로 실행되는 Dataplex 태스크가 생성됩니다. 실행할 때마다 실행 시작 및 종료 시간, 실행 상태, 로그, 생성된 출력과 같은 실행 메타데이터를 캡처하는 작업이 생성됩니다.

예약된 SQL 스크립트 또는 노트북에 대한 실행이 트리거되면 노트북 또는 SQL 스크립트의 현재 버전이 실행됩니다. 즉, 노트북 또는 SQL 스크립트를 예약하고 나중에 콘텐츠를 업데이트하면 업데이트가 노트북 또는 SQL 스크립트의 예약된 실행에도 반영됩니다.

비용

예약된 SQL 스크립트 및 예약된 노트북은 Dataproc 서버리스를 사용하여 작업 실행을 트리거합니다. 사용량에 따른 요금은 Dataproc 가격 책정 모델에 따라 청구되며 Dataplex가 아닌 Dataproc에 요금이 표시됩니다.

시작하기 전에

다음 문서에 설명된 기본 요건을 검토하고 완료합니다.

• Data Exploration Workbench 사용의 시작하기 전에 섹션

• 커스텀 Spark 및 SparkSQL 태스크 예약의 시작하기 전에 섹션

  참고: 커스텀 Spark 및 SparkSQL 태스크 예약에 설명된 태스크 서비스 계정과 관련된 안내는 SQL 스크립트 및 노트북 모두로 확장되며 SQL 스크립트 및 노트북을 예약하는 데 사용되는 서비스 계정에도 적용됩니다.
  
  커스텀 Spark 및 SparkSQL 태스크 예약에 설명된 비공개 Google 액세스 사용 설정에 관한 안내는 SQL 스크립트 및 노트북에 사용되는 네트워크와 관련이 있습니다. Google Cloud 콘솔을 사용하여 SQL 스크립트 또는 노트북을 예약할 때는 기본 서브네트워크만 사용할 수 있습니다. 자세한 내용은 알려진 제한사항을 참고하세요.

SQL 스크립트 또는 노트북 일정이 BigQuery API를 사용하는 경우 서비스 계정에 서비스 사용량 소비자 역할(roles/serviceusage.serviceUsageConsumer)을 부여해야 합니다.

알려진 제한사항

• Google Cloud 콘솔을 사용하여 노트북을 예약할 때 선택한 환경에 구성된 추가 Python 패키지는 런타임 시 예약된 노트북에 사용할 수 없습니다. 런타임에 이를 사용할 수 있게 하려면 필요한 추가 패키지가 있는 컨테이너 이미지를 참조하는 노트북 예약을 만들어야 합니다. 자세한 내용은 커스텀 패키지를 사용하여 노트북 예약을 참조하세요.

• Google Cloud 콘솔을 사용해 노트북을 예약할 때 커스텀 컨테이너 이미지를 참조하는 기능은 지원되지 않습니다. 대신 gcloud CLI를 사용하세요.

• 일정을 만든 후에는 수정할 수 없습니다. 일정 매개변수를 업데이트하려면 새 매개변수로 일정을 다시 만들어야 합니다.

• 일정에 사용할 SQL 스크립트 또는 노트북의 특정 버전을 정의할 수 없습니다. 일정이 트리거되면 SQL 스크립트 또는 노트북의 현재 버전이 사용됩니다.

• Google Cloud 콘솔을 사용하여 SQL 스크립트 및 노트북을 예약하면 기본 서브네트워크가 사용됩니다. 다른 네트워크 또는 서브네트워크를 지정하려면 gcloud CLI를 사용합니다.

또한 탐색의 알려진 제한사항을 검토하세요.

SQL 스크립트 일정 만들기 및 관리

예약된 SQL 스크립트의 런타임 구성

SQL 스크립트가 예약되면 Dataplex 태스크로 실행됩니다. Google Cloud 콘솔을 사용하여 일정을 만들면 예약된 SQL 스크립트의 해당 태스크 런타임 매개변수가 다음 매핑을 기반으로 해당 SQL 스크립트의 환경에서 상속됩니다.

환경 구성 매개변수	예약된 SQL 스크립트 태스크 구성 매개변수
기본 디스크 크기	컨테이너 이미지/속성:    spark.dataproc.driver.disk.size    spark.dataproc.executor.disk.size
노드 수	일괄/실행자 수
최대 노드 수	일괄/최대 실행자 수
이미지 버전	상속되지 않음
JAR 파일	컨테이너 이미지/Java JARS
Python 패키지	상속되지 않음
추가 속성	컨테이너 이미지/속성

SQL 스크립트 예약

콘솔

1. Google Cloud 콘솔에서 Dataplex 탐색 페이지로 이동합니다.

   Dataplex Explore로 이동

2. Spark SQL 스크립트 목록에서 단일 SQL 스크립트를 선택하거나 Spark SQL 편집기에서 SQL 스크립트를 열어 예약할 SQL 스크립트를 선택합니다.

3. 일정 메뉴에서 일정 만들기를 클릭합니다.

4. 일정 이름 필드에 예약된 인스턴스의 이름을 입력합니다.

5. 일정 옵션 섹션에서 SQL 스크립트를 한 번만 실행할지 아니면 반복 실행할지 선택합니다.

   1. 한 번 실행을 선택할 경우 시작 메뉴의 옵션을 사용하여 SQL 스크립트를 즉시 실행할지 아니면 예약된 시간에 실행할지 지정합니다. 예약된 실행의 경우 시작 날짜와 실행 시간을 지정합니다.

   2. 반복을 선택하는 경우 SQL 스크립트를 매일, 매주, 매월 또는 크론 표현식을 사용해 지정한 커스텀 일정으로 실행할지 지정합니다. 또한 최초 예약된 실행의 시작 날짜와 실행 시간도 지정합니다.

6. 결과 출력 위치 섹션에서 다음을 수행합니다.

   1. 출력 폴더 이름 필드에서 찾아보기를 클릭하고 스크립트 출력을 저장할 Cloud Storage 버킷에서 폴더를 선택합니다.

   2. 선택을 클릭합니다.

   3. 스크립트 출력 형식을 선택합니다. 지원되는 형식은 CSV, JSON, ORC, Parquet입니다.

7. 예약된 스크립트 사용자 인증 정보 섹션의 사용자 서비스 계정 메뉴에서 서비스 계정을 선택합니다.

8. 일정을 클릭합니다.

gcloud

gcloud CLI를 사용하여 SQL 스크립트를 예약하는 방법에 대한 자세한 내용은 SparkSQL 태스크 예약을 참조하세요.

참고: SparkSQL 태스크 예약 섹션의 --spark-sql-script-file 매개변수 설명에는 이 매개변수의 값으로 Cloud Storage의 URI를 사용할 수 있다고 나와 있습니다. 이 기능은 지원되지 않습니다. --spark-sql-script-file 매개변수에는 SQL 스크립트 콘텐츠 경로만 지정해야 합니다.

REST

API 탐색기를 사용하여 태스크를 만듭니다.

참고: REST 참조 문서의 SparkTaskConfig 리소스에 대한 설명에는 sqlScriptFile 필드의 값으로 Cloud Storage의 URI를 사용할 수 있다고 나와 있습니다. 이 기능은 지원되지 않습니다. sqlScriptFile 필드에는 SQL 스크립트 콘텐츠 경로만 지정해야 합니다.

SQL 스크립트 일정 관리

콘솔

모든 SQL 스크립트 일정 목록 열기

1. Google Cloud 콘솔에서 Dataplex Process 페이지로 이동합니다.

2. 예약된 쿼리 탭을 클릭하여 SQL 스크립트 일정 목록을 확인합니다.

특정 SQL 스크립트의 모든 일정 목록 열기

1. Google Cloud 콘솔에서 Dataplex 탐색 페이지로 이동합니다.

2. 필요한 SQL 스크립트를 선택합니다.

3. 일정 메뉴에서 일정 보기를 클릭합니다.

   예약된 쿼리 탭이 열리고 선택한 SQL 스크립트로 필터링된 SQL 스크립트 일정 목록이 표시됩니다.

SQL 스크립트 일정의 세부정보 보기

1. 예약된 쿼리 탭으로 이동하고 필요한 SQL 스크립트 일정을 선택합니다.

2. 세부정보 탭을 클릭하여 SQL 스크립트 일정의 세부정보와 예약된 SQL 스크립트 콘텐츠 미리보기를 봅니다.

SQL 스크립트 일정 활성화 및 비활성화

1. 예약된 쿼리 탭으로 이동하고 필요한 SQL 스크립트 일정을 선택합니다.

2. 중지를 클릭하여 활성 SQL 스크립트 일정을 비활성화합니다.

3. 사용 설정을 클릭하여 비활성 SQL 스크립트 일정을 활성화합니다.

기존 SQL 스크립트 일정 삭제

1. 예약된 쿼리 탭으로 이동하고 필요한 SQL 스크립트 일정을 선택합니다.

2. 삭제를 클릭하여 기존 SQL 스크립트 일정을 영구 삭제합니다.

로그 보기 및 SQL 스크립트 일정 관리

1. 예약된 쿼리 탭으로 이동하고 필요한 SQL 스크립트 일정을 선택합니다.

2. 작업 탭을 클릭한 후 보려는 예약된 SQL 스크립트 실행의 작업 ID를 클릭합니다.

3. 로그 보기를 클릭하여 Cloud Logging에서 선택한 예약된 SQL 스크립트 실행과 관련된 로그를 봅니다.

4. Dataproc 배치 ID를 클릭하여 Google Cloud 콘솔에서 Dataproc 페이지를 엽니다. 해당 Dataproc 서버리스 세션의 세부정보에 액세스합니다.

5. 출력 라벨 옆에 있는 Cloud Storage에서 관리를 클릭하여 Google Cloud 콘솔에서 Cloud Storage 페이지를 엽니다. SQL 스크립트 실행 출력이 포함된 해당 Cloud Storage 버킷의 세부정보에 액세스합니다.

gcloud

gcloud CLI를 사용하여 예약된 SQL 스크립트를 모니터링하는 방법에 대한 자세한 내용은 태스크 모니터링의 gcloud 탭을 참조하세요.

gcloud CLI를 사용하여 예약된 SQL 스크립트를 관리하는 방법에 대한 자세한 내용은 일정 관리의 gcloud 탭을 참조하세요.

REST

REST를 사용하여 예약된 SQL 스크립트를 모니터링하는 방법에 대한 자세한 내용은 태스크 모니터링의 REST 탭을 참조하세요.

REST를 사용하여 예약된 SQL 스크립트를 관리하는 방법에 대한 자세한 내용은 일정 관리의 REST 탭을 참조하세요.

예약된 SQL 스크립트의 출력

예약된 SQL 스크립트가 실행될 때마다 Cloud Storage 폴더에 지정된 다음과 같은 구조의 위치에 출력이 저장됩니다.

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

노트북 일정 만들기 및 관리

예약된 노트북의 런타임 구성

노트북이 예약되면 Dataplex 태스크로 실행됩니다. Google Cloud 콘솔을 사용하여 일정을 만들면 예약된 노트북의 해당 태스크 런타임 매개변수가 다음 매핑을 기반으로 해당 노트북의 환경에서 상속됩니다.

환경 구성 매개변수	예약된 노트북 태스크 구성 매개변수
기본 디스크 크기	컨테이너 이미지/속성:    spark.dataproc.driver.disk.size    spark.dataproc.executor.disk.size
노드 수	일괄/실행자 수
최대 노드 수	일괄/최대 실행자 수
이미지 버전	상속되지 않음
JAR 파일	컨테이너 이미지/Java JARS
Python 패키지	상속되지 않음
추가 속성	컨테이너 이미지/속성

참고: 노트북이 예약되면 해당 Dataplex 태스크 매개변수가 원래 환경 구성을 기반으로 고정됩니다. 원본 노트북 환경의 매개변수를 변경해도 해당 Dataplex 태스크의 구성에는 영향을 주지 않습니다.

커스텀 패키지로 노트북 예약

대화형 노트북의 경우 환경을 구성할 때 Dataplex를 통해 환경에 프로비저닝된 사용자 세션에 설치할 커스텀 Python 패키지를 지정할 수 있습니다. 이러한 노트북이 예약되면 해당 환경에 구성된 커스텀 Python 패키지가 런타임 시 예약된 노트북에 제공되지 않으며, 기본 런타임 환경에는 Dataproc 서버리스 Spark 런타임 버전 1.0 구성요소만 포함됩니다. 런타임 시 예약된 노트북에서 커스텀 Python 패키지를 사용할 수 있도록 필요한 커스텀 패키지가 있는 커스텀 컨테이너 이미지를 제공합니다.

Google Cloud 콘솔을 사용하여 노트북을 예약할 때 커스텀 컨테이너 이미지를 지정하는 기능은 지원되지 않습니다. 대신 gcloud CLI를 사용하세요. 자세한 내용은 노트북 예약을 참조하세요.

커스텀 패키지가 구성된 환경으로 노트북을 예약하면 다음 경고가 표시됩니다.

Selected environment  has additional Python packages configured.
These packages will not be available in the default runtime for the scheduled notebook
when scheduling in the Console. To make the required additional Python packages
available in the runtime, please create Notebook Schedule using gcloud command
instead, referencing a container image with required additional packages.

예약된 노트북의 커스텀 컨테이너 이미지 빌드

예약된 노트북의 컨테이너 이미지를 설정하고 컨테이너 이미지 Dockerfile에 필요한 커스텀 Python 패키지를 설치하는 방법은 Spark용 Dataproc 서버리스의 커스텀 컨테이너 이미지 빌드를 참조하세요.

컨테이너 이미지에 다음 conda 패키지를 설치했는지 확인합니다.

• gcsfs
• google-cloud-bigquery
• google-cloud-storage
• google-auth
• ipykernel
• papermill

참고: google-auth, ipykernel, papermill을 제외한 패키지는 Spark용 Dataproc 서버리스의 커스텀 컨테이너 이미지 빌드에 설명된 샘플 Dockerfile에 있습니다.

컨테이너 이미지에 gcloud 구성요소를 설치하려면 컨테이너 이미지 Dockerfile을 열고 다음 단계를 완료하세요.

1. 설치할 conda 패키지 목록에 google-cloud-sdk 패키지를 추가합니다.

2. conda 패키지 설치 단계 후 다음 줄을 추가합니다.

   # (Optional) Installing gcloud components
   RUN gcloud components install alpha beta bq
   

노트북 예약

콘솔

1. Google Cloud 콘솔에서 Dataplex 탐색 페이지로 이동합니다.

   Dataplex Explore로 이동

2. 노트북 보기에서 단일 노트북을 선택하거나 노트북 세부정보 페이지에서 노트북을 열어 예약할 노트북을 선택합니다.

3. 일정 메뉴에서 일정 만들기를 클릭합니다.

4. 일정 이름 필드에 예약된 인스턴스의 이름을 입력합니다.

5. 일정 옵션 섹션에서 노트북을 한 번만 실행할지 아니면 반복 실행할지 선택합니다.

   1. 한 번 실행을 선택할 경우 시작 메뉴의 옵션을 사용하여 노트북을 즉시 실행할지 아니면 예약된 시간에 실행할지 지정합니다. 예약된 실행의 경우 시작 날짜와 실행 시간을 지정합니다.

   2. 반복을 선택하는 경우 노트북을 매일, 매주, 매월 또는 크론 표현식을 사용해 지정한 커스텀 일정으로 실행할지 지정합니다. 또한 최초 예약된 실행의 시작 날짜와 실행 시간도 지정합니다.

6. 결과 출력 위치 섹션에서 노트북 출력을 저장할 위치를 선택합니다.

   1. 출력 폴더 이름 필드에서 찾아보기를 클릭하고 노트북 출력을 저장할 Cloud Storage 버킷에서 폴더를 선택합니다.

   2. 선택을 클릭합니다.

   3. 스크립트 출력 형식을 선택합니다. 지원되는 형식은 CSV, JSON, ORC, Parquet입니다.

7. 예약된 노트북 사용자 인증 정보 섹션의 사용자 서비스 계정 메뉴에서 서비스 계정을 선택합니다.

8. 매개변수 섹션에서 새로 추가를 클릭하여 노트북의 실행 매개변수를 키-값 쌍으로 추가합니다.

9. 일정을 클릭합니다.

gcloud

다음 추가 매개변수를 사용하여 Spark(Java 또는 Python) 태스크 예약에 설명된 gcloud CLI 명령어를 실행합니다.

매개변수	설명
--notebook	입력 노트북의 노트북 콘텐츠 경로입니다. 실행 인수는 환경 변수로 액세스할 수 있습니다. 예를 들면 TASK_key=value입니다. 참고: 노트북을 태스크로 예약하는 방법에 대한 gcloud 참조 문서에는 --notebook 매개변수의 값으로 노트북 파일의 Cloud Storage URI를 사용할 수 있다고 나와 있습니다. 이 기능은 지원되지 않습니다. --notebook 매개변수에는 노트북 콘텐츠 경로만 지정해야 합니다.
--notebook-archive-uris	각 실행자의 작업 디렉터리로 추출할 보관 파일의 Cloud Storage URI입니다. 지원되는 파일 형식은 JAR, tar, tar.gz, tgz, zip입니다.
--notebook-file-uris	각 실행자의 작업 디렉터리에 배치할 파일의 Cloud Storage URI입니다.
Dataproc 서버리스를 사용할 때 태스크에 필요한 컴퓨팅 리소스
--notebook-batch-executors-count	작업 실행자 수입니다.
--notebook-batch-max-executors-count	구성 가능한 최대 실행자 수입니다. notebook-batch-max-executors-count가 notebook-batch-executors-count보다 크면 자동 확장이 사용 설정됩니다.
컨테이너 이미지 런타임 구성
--notebook-container-image	선택사항: 작업에 대한 커스텀 컨테이너 이미지입니다.
--notebook-container-image-java-jars	클래스 경로에 추가할 Java JAR 목록입니다. 유효한 입력에는 JAR 바이너리에 대한 Cloud Storage URI가 포함됩니다. 예를 들면 다음과 같습니다. gs://BUCKET_NAME/my/path/to/file.jar
--notebook-container-image-properties	데몬 구성 파일에 설정할 속성입니다. 속성 키는 prefix:property 형식으로 지정됩니다. 예를 들면 : core:hadoop.tmp.dir입니다. 자세한 내용은 클러스터 속성을 참조하세요.
인프라를 실행하는 데 사용되는 Cloud VPC 네트워크
--notebook-vpc-network-tags	작업에 적용할 네트워크 태그 목록입니다.
Cloud VPC 네트워크 식별자입니다. 다음 중 최대 1개만 지정할 수 있습니다.
--notebook-vpc-network-name	작업이 실행되는 Cloud VPC 네트워크입니다. 기본적으로 프로젝트 내에서 Default라는 이름의 Cloud VPC 네트워크가 사용됩니다.
--notebook-vpc-sub-network-name	작업이 실행되는 Cloud VPC 서브네트워크입니다.
노트북 출력 위치
--execution-args	노트북 태스크의 경우 다음 인수는 필수이며 TASK_ARGS로 전달해야 합니다.
	--execution-args=^::^TASK_ARGS="--output_location,CLOUD_STORAGE_URI_OF_OUTPUT_DIRECTORY"

다음은 노트북 예약에 사용되는 gcloud 명령어의 예시입니다.

gcloud dataplex tasks create sample-task --project=sample-project --location=us-central1 --lake=my-lake --trigger-type=ON_DEMAND --notebook="projects/my-project-id/locations/us-central1/lakes/my-lake/content/my-notebook.ipynb" --execution-service-account=[e-mail]  --execution-args=^::^TASK_ARGS="--output_location,gs://my-bucket/Demo" --notebook-batch-executors-count=2 --notebook-batch-max-executors-count=5 --notebook-container-image=container-image --notebook-container-image-java-jars=java-jar1,java-jar-2

REST

API 탐색기를 사용하여 태스크를 만듭니다.

참고: REST 참조 문서의 NotebookTaskConfig 리소스에 대한 설명에는 notebook 필드의 값으로 Cloud Storage의 URI를 사용할 수 있다고 나와 있습니다. 이 기능은 지원되지 않습니다. notebook 매개변수에는 노트북 콘텐츠 경로만 지정해야 합니다.

노트북 일정 관리

콘솔

모든 노트북 일정 목록 열기

1. Google Cloud 콘솔에서 Dataplex Process 페이지로 이동합니다.

2. 예약된 노트북 탭을 클릭하여 SQL 스크립트 일정 목록을 봅니다.

특정 노트북의 모든 일정 목록 열기

1. Google Cloud 콘솔에서 Dataplex 탐색 페이지로 이동합니다.

2. 필요한 노트북을 선택합니다.

3. 일정 메뉴에서 일정 보기를 클릭합니다.

   예약된 쿼리 탭이 열리고 선택한 노트북으로 필터링된 노트북 일정 목록이 표시됩니다.

노트북 일정 세부정보 보기

1. 예약된 노트북 탭으로 이동하고 필요한 노트북 일정을 선택합니다.

2. 세부정보를 클릭하여 노트북 일정의 세부정보와 예약된 노트북 콘텐츠 미리보기를 확인합니다.

노트북 일정 활성화 및 비활성화

1. 예약된 노트북 탭으로 이동하고 필요한 노트북 일정을 선택합니다.

2. 중지를 클릭하여 활성 노트북 일정을 비활성화합니다.

3. 사용 설정을 클릭하여 비활성 노트북 일정을 활성화합니다.

기존 노트북 일정 삭제

1. 예약된 노트북 탭으로 이동하고 필요한 노트북 일정을 선택합니다.

2. 기존 노트북 일정을 영구 삭제하려면 삭제를 클릭합니다.

로그 보기 및 노트북 일정 관리

1. 예약된 노트북 탭으로 이동하고 필요한 노트북 일정을 선택합니다.

2. 작업 탭을 클릭한 후 보려는 예약된 노트북 실행의 작업 ID를 클릭합니다.

3. 미리보기 출력 섹션에서 노트북 실행의 출력을 검토합니다.

4. 로그 보기를 클릭하여 Cloud Logging에서 선택한 예약된 노트북 실행과 관련된 로그를 봅니다.

5. Dataproc 배치 ID를 클릭하여 Google Cloud 콘솔에서 Dataproc 페이지를 엽니다. 해당 Dataproc 서버리스 세션의 세부정보에 액세스합니다.

6. 출력 라벨 옆에 있는 Cloud Storage에서 관리를 클릭하여 Google Cloud 콘솔에서 Cloud Storage 페이지를 엽니다. 노트북 실행 출력이 포함된 해당 Cloud Storage 버킷의 세부정보에 액세스합니다.

gcloud

gcloud CLI를 사용하여 예약된 노트북을 모니터링하는 방법에 대한 자세한 내용은 태스크 모니터링의 gcloud 탭을 참조하세요.

gcloud CLI를 사용하여 예약된 노트북을 관리하는 방법에 대한 자세한 내용은 일정 관리의 gcloud 탭을 참조하세요.

REST

REST를 사용하여 예약된 노트북을 모니터링하는 방법에 대한 자세한 내용은 태스크 모니터링의 REST 탭을 참조하세요.

REST를 사용하여 예약된 노트북을 관리하는 방법에 대한 자세한 내용은 일정 관리의 REST 탭을 참조하세요.

예약된 노트북 출력

예약된 노트북이 실행될 때마다 Cloud Storage 폴더에 지정된 다음과 같은 구조의 위치에 출력이 저장됩니다.

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

다음 단계

• 커스텀 Spark 및 Spark SQL 태스크 예약
• Dataplex 태스크에 대한 경고 및 알림 설정