Refresh directory tables automatically for Google Cloud Storage
Refresh directory tables automatically for Google Cloud Storage (Google Cloud Storage용 디렉터리 테이블 자동 새로 고침)
이 주제는 Google Cloud Pub/Sub 메시지를 사용해 GCS(Google Cloud Storage) 이벤트에 대한 디렉터리 테이블 메타데이터 새로 고침을 트리거하는 지침을 제공해요.
본문
Note
이 주제의 단계를 완료하려면 스키마에 대한 CREATE STAGE 권한이 있는 역할을 사용해야 해요.
또한 Google Cloud(GC)에 대한 관리자 접근이 있어야 해요. GCP 관리자가 아니라면 Prerequisites 단계를 완료하도록 GCP 관리자에게 요청해요.
OBJECT_DELETE와 OBJECT_FINALIZE 이벤트만 디렉터리 테이블 새로 고침을 트리거한다는 점을 주목해요. Snowflake는 비용, 이벤트 노이즈, 지연 시간을 줄이기 위해 디렉터리 테이블에 지원되는 이벤트만 보낼 것을 권장해요.
클라우드 플랫폼 지원
GCS Pub/Sub 이벤트 메시지를 사용한 자동 새로 고침 트리거는 지원 클라우드 플랫폼 중 어느 곳에 호스팅된 Snowflake 계정에서도 지원돼요.
Cloud Storage에 대한 안전한 접근 구성
Note
데이터 파일을 저장하는 GCS 버킷에 대한 안전한 접근을 이미 구성했다면 이 섹션을 건너뛸 수 있어요.
이 섹션은 클라우드 저장소에 대한 인증 책임을 Snowflake 신원 및 접근 관리(IAM) 엔티티로 위임하도록 Snowflake 저장 통합 객체를 구성하는 방법을 설명해요.
이 섹션은 저장 통합을 사용해 Snowflake가 외부(즉, Cloud Storage) 스테이지에서 참조되는 Google Cloud Storage 버킷에서 데이터를 읽고 쓰게 하는 방법을 설명해요. 통합은 시크릿 키나 접근 토큰 같은 명시적 클라우드 공급자 자격 증명을 전달할 필요가 없게 하는 명명된 일급(first-class) Snowflake 객체예요. 대신 통합 객체는 Cloud Storage 서비스 계정을 참조해요. 조직의 관리자가 Cloud Storage 계정에서 서비스 계정에 권한을 부여해요.
관리자는 또한 사용자를 이 통합을 사용하는 외부 스테이지가 접근하는 특정 Cloud Storage 버킷(및 선택적 경로) 집합으로 제한할 수 있어요.
Note
- 이 섹션의 지침을 완료하려면 Cloud Storage 프로젝트에 프로젝트 편집자로 접근해야 해요. 프로젝트 편집자가 아니라면 Cloud Storage 관리자에게 이 작업을 수행하도록 요청해요.
- Snowflake가 저장소가 호스팅된 Google Cloud Storage 리전을 지원하는지 확인해요. 자세한 내용은 지원 클라우드 리전을 참고해요.
다음 다이어그램은 Cloud Storage 스테이지의 통합 흐름을 보여 줘요.
- 외부(즉, Cloud Storage) 스테이지가 정의에서 저장 통합 객체를 참조해요.
- Snowflake가 저장 통합을 계정용으로 만들어진 Cloud Storage 서비스 계정과 자동으로 연결해요. Snowflake 계정의 모든 GCS 저장 통합이 참조하는 단일 서비스 계정을 만들어요.
- Cloud Storage 프로젝트의 프로젝트 편집자가 스테이지 정의에서 참조된 버킷에 접근할 수 있도록 서비스 계정에 권한을 부여해요. 여러 외부 스테이지 객체가 다른 버킷·경로를 참조하고 인증에 같은 통합을 사용할 수 있다는 점을 주목해요.
사용자가 스테이지에서 데이터를 로드하거나 언로드할 때 Snowflake는 버킷에 대해 서비스 계정에 부여된 권한을 확인한 뒤 접근을 허용하거나 거부해요.
Step 1: Snowflake에서 Cloud Storage 통합 생성
CREATE STORAGE INTEGRATION 명령으로 통합을 만들어요. 통합은 외부 클라우드 저장소에 대한 인증 책임을 Snowflake 생성 엔티티(즉, Cloud Storage 서비스 계정)로 위임하는 Snowflake 객체예요. Cloud Storage 버킷에 접근하기 위해 Snowflake는 데이터 파일을 저장하는 버킷(들)에 접근 권한을 부여받을 수 있는 서비스 계정을 만들어요.
단일 저장 통합은 여러 외부(즉, GCS) 스테이지를 지원할 수 있어요. 스테이지 정의의 URL은 STORAGE_ALLOWED_LOCATIONS 파라미터에 지정된 GCS 버킷(및 선택적 경로)과 일치해야 해요.
Note
계정 관리자(ACCOUNTADMIN 역할을 가진 사용자) 또는 전역 CREATE INTEGRATION 권한이 있는 역할만 이 SQL 명령을 실행할 수 있어요.
CREATE STORAGE INTEGRATION <integration_name>
TYPE = EXTERNAL_STAGE
STORAGE_PROVIDER = 'GCS'
ENABLED = TRUE
STORAGE_ALLOWED_LOCATIONS = ('gcs://<bucket>/<path>/', 'gcs://<bucket>/<path>/')
[ STORAGE_BLOCKED_LOCATIONS = ('gcs://<bucket>/<path>/', 'gcs://<bucket>/<path>/') ]
여기서:
*integration_name*은 새 통합의 이름이에요.*bucket*은 데이터 파일을 저장하는 Cloud Storage 버킷의 이름(예:mybucket)이에요. 필수 STORAGE_ALLOWED_LOCATIONS 파라미터와 선택적 STORAGE_BLOCKED_LOCATIONS 파라미터는 이 통합을 참조하는 스테이지가 생성되거나 수정될 때 각각 이러한 버킷에 대한 접근을 제한하거나 차단해요.*path*는 버킷의 객체에 대한 세밀한 제어를 제공하는 데 사용할 수 있는 선택적 경로예요.
다음 예는 이 통합을 사용하는 외부 스테이지를 두 버킷·경로 중 하나만 참조하도록 명시적으로 제한하는 통합을 만들어요. 이후 단계에서 이러한 버킷·경로 중 하나를 참조하는 외부 스테이지를 만들 거예요.
이 통합을 사용하는 추가 외부 스테이지가 허용된 버킷·경로를 참조할 수 있어요:
CREATE STORAGE INTEGRATION gcs_int
TYPE = EXTERNAL_STAGE
STORAGE_PROVIDER = 'GCS'
ENABLED = TRUE
STORAGE_ALLOWED_LOCATIONS = ('gcs://mybucket1/path1/', 'gcs://mybucket2/path2/')
STORAGE_BLOCKED_LOCATIONS = ('gcs://mybucket1/path1/sensitivedata/', 'gcs://mybucket2/path2/sensitivedata/');
Step 2: Snowflake 계정의 Cloud Storage 서비스 계정 검색
DESCRIBE INTEGRATION 명령을 실행해 Snowflake 계정용으로 자동 생성된 Cloud Storage 서비스 계정의 ID를 검색해요:
DESC STORAGE INTEGRATION <integration_name>;
여기서:
*integration_name*은 Step 1: Snowflake에서 Cloud Storage 통합 생성에서 만든 통합의 이름이에요(이 주제에서).
예:
DESC STORAGE INTEGRATION gcs_int;
+-----------------------------+---------------+-----------------------------------------------------------------------------+------------------+
| property | property_type | property_value | property_default |
+-----------------------------+---------------+-----------------------------------------------------------------------------+------------------+
| ENABLED | Boolean | true | false |
| STORAGE_ALLOWED_LOCATIONS | List | gcs://mybucket1/path1/,gcs://mybucket2/path2/ | [] |
| STORAGE_BLOCKED_LOCATIONS | List | gcs://mybucket1/path1/sensitivedata/,gcs://mybucket2/path2/sensitivedata/ | [] |
| STORAGE_GCP_SERVICE_ACCOUNT | String | [email protected] | |
+-----------------------------+---------------+-----------------------------------------------------------------------------+------------------+
출력의 STORAGE_GCP_SERVICE_ACCOUNT 속성은 Snowflake 계정용으로 만들어진 Cloud Storage 서비스 계정(즉, [email protected])을 보여 줘요. 전체 Snowflake 계정에 대해 단일 Cloud Storage 서비스 계정을 프로비저닝해요. 모든 Cloud Storage 통합이 그 서비스 계정을 사용해요.
Step 3: 버킷 객체에 접근할 수 있도록 서비스 계정에 권한 부여
다음 단계별 지침은 Cloud Storage 버킷을 사용해 데이터를 로드·언로드할 수 있도록 Google Cloud 콘솔에서 Snowflake에 IAM 접근 권한을 구성하는 방법을 설명해요.
사용자 정의 IAM 역할 생성
버킷에 접근하고 객체를 가져오는 데 필요한 권한이 있는 사용자 정의 역할을 만들어요.
- 프로젝트 편집자로 Google Cloud 콘솔에 로그인해요.
- 홈 대시보드에서 IAM & Admin » Roles를 선택해요.
- Create Role을 선택해요.
- 사용자 정의 역할의 Title과 선택적 Description을 입력해요.
- Add Permissions을 선택해요.
- 권한 목록을 필터링하고 목록에서 다음을 추가해요.
| 작업(들) | 필요한 권한 |
|---|---|
| 데이터 로드만 | storage.buckets.get storage.objects.get storage.objects.list |
| purge 옵션으로 데이터 로드, 스테이지에서 REMOVE 명령 실행 | storage.buckets.get storage.objects.delete storage.objects.get storage.objects.list |
| 데이터 로드 및 언로드 | storage.buckets.get(데이터 전송 비용 계산용) storage.objects.create storage.objects.delete storage.objects.get storage.objects.list |
| 데이터 언로드만 | storage.buckets.get storage.objects.create storage.objects.delete storage.objects.list |
| COPY FILES로 외부 스테이지에 파일 복사 | 다음 추가 권한 필요: storage.multipartUploads.abort storage.multipartUploads.create storage.multipartUploads.list storage.multipartUploads.listParts |
- Add를 선택해요.
- Create를 선택해요.
Cloud Storage 서비스 계정에 사용자 정의 역할 할당
- 프로젝트 편집자로 Google Cloud 콘솔에 로그인해요.
- 홈 대시보드에서 Cloud Storage » Buckets를 선택해요.
- 버킷 목록을 필터링하고 저장 통합을 만들 때 지정한 버킷을 선택해요.
- Permissions » View by principals를 선택한 다음 Grant access를 선택해요.
- Add principals 아래에서 DESC STORAGE INTEGRATION 명령 출력에서 검색한 서비스 계정 이름을 붙여넣어요.
- Assign roles 아래에서 이전에 만든 사용자 정의 IAM 역할을 선택한 다음 Save를 선택해요.
Important
Google Cloud 조직이 2024년 5월 3일 이후에 생성된 경우, Google Cloud는 프로젝트 조직 정책에 도메인 제한 제약을 적용해요. 기본 제약은 허용된 유일한 값으로 도메인을 나열해요.
Snowflake 서비스 계정이 저장소에 접근하도록 허용하려면 도메인 제한을 업데이트해야 해요.
Cloud Key Management Service 암호화 키에 Cloud Storage 서비스 계정 권한 부여
Note
이 단계는 GCS 버킷이 Google Cloud Key Management Service(Cloud KMS)에 저장된 키로 암호화된 경우에만 필요해요.
- 프로젝트 편집자로 Google Cloud 콘솔에 로그인해요.
- 홈 대시보드에서 Security » Key Management를 검색해 선택해요.
- GCS 버킷에 할당된 키 링을 선택해요.
- 오른쪽 위 모서리의 SHOW INFO PANEL을 클릭해요. 키 링의 정보 패널이 나와요.
- ADD PRINCIPAL 버튼을 클릭해요.
- New principals 필드에서 Step 2: Snowflake 계정의 Cloud Storage 서비스 계정 검색의 DESCRIBE INTEGRATION 출력에서 가져온 서비스 계정 이름을 검색해요(이 주제에서).
- Select a role 드롭다운에서
Cloud KMS CrytoKey Encryptor/Decryptor역할을 선택해요. - Save 버튼을 클릭해요. 서비스 계정 이름이 정보 패널의 Cloud KMS CrytoKey Encryptor/Decryptor 역할 드롭다운에 추가돼요.
Note
SYSTEM$VALIDATE_STORAGE_INTEGRATION 함수를 사용해 저장 통합 구성을 검증할 수 있어요.
GCS Pub/Sub을 사용한 자동화 구성
전제 조건
이 주제의 지침은 다음 항목이 생성·구성되었다고 가정해요.
GCP 계정:
- GCS 버킷에서 이벤트 메시지를 받는 Pub/Sub 토픽. 자세한 내용은 Pub/Sub 토픽 생성(이 주제에서)을 참고해요.
- Pub/Sub 토픽에서 이벤트 메시지를 받는 구독. 자세한 내용은 Pub/Sub 구독 생성(이 주제에서)을 참고해요.
지침은 Pub/Sub 문서를 참고해요.
Snowflake:
- 데이터가 로드될 Snowflake 데이터베이스의 대상 테이블.
Pub/Sub 토픽 생성
Cloud Shell 또는 Cloud SDK를 사용해 Pub/Sub 토픽을 만들어요.
지정된 GCS 버킷의 활동을 수신하도록 토픽을 만들고 활성화하려면 다음 명령을 실행해요:
$ gsutil notification create -t <topic> -f json -e OBJECT_FINALIZE -e OBJECT_DELETE gs://<bucket-name>
여기서:
topic은 토픽의 이름이에요.bucket-name은 GCS 버킷의 이름이에요.
토픽이 이미 존재하면 명령이 그것을 사용하고, 그렇지 않으면 새 토픽이 생성돼요.
자세한 내용은 Pub/Sub 문서의 Cloud Storage에 Pub/Sub 알림 사용을 참고해요.
Pub/Sub 구독 생성
Cloud Console, gcloud 명령줄 도구, 또는 Cloud Pub/Sub API를 사용해 Pub/Sub 토픽에 풀 전달이 있는 구독을 만들어요. 지침은 Pub/Sub 문서의 토픽 및 구독 관리를 참고해요.
Note
- 기본 pull 전달을 사용하는 Pub/Sub 구독만 Snowflake에서 지원돼요. Push 전달은 지원되지 않아요.
Pub/Sub 구독 ID 검색
Pub/Sub 토픽 구독 ID는 이 지침에서 Snowflake가 이벤트 메시지에 접근하도록 허용하는 데 사용돼요.
- 프로젝트 편집자로 Google Cloud Platform 콘솔에 로그인해요.
- 홈 대시보드에서 Big Data » Pub/Sub » Subscriptions를 선택해요.
- 토픽 구독의 Subscription ID 컬럼에서 ID를 복사해요.
Step 1: Snowflake에서 알림 통합 생성
CREATE NOTIFICATION INTEGRATION 명령으로 알림 통합을 만들어요.
알림 통합은 Pub/Sub 구독을 참조해요. Snowflake는 알림 통합을 계정용으로 만들어진 GCS 서비스 계정과 연결해요. Snowflake 계정의 모든 GCS 알림 통합이 참조하는 단일 서비스 계정을 만들어요.
Note
- 계정 관리자(ACCOUNTADMIN 역할을 가진 사용자) 또는 전역 CREATE INTEGRATION 권한이 있는 역할만 이 SQL 명령을 실행할 수 있어요.
- 알림 통합용 GCS 서비스 계정은 저장 통합용으로 만든 서비스 계정과 달라요.
- 단일 알림 통합은 단일 Google Cloud Pub/Sub 구독을 지원해요. 여러 알림 통합에서 같은 Pub/Sub 구독을 참조하면 이벤트 알림이 알림 통합 간에 분할되므로 대상 테이블의 데이터가 누락될 수 있어요.
CREATE NOTIFICATION INTEGRATION <integration_name>
TYPE = QUEUE
NOTIFICATION_PROVIDER = GCP_PUBSUB
ENABLED = true
GCP_PUBSUB_SUBSCRIPTION_NAME = '<subscription_id>';
여기서:
integration_name은 새 통합의 이름이에요.subscription_id는 Pub/Sub 구독 ID 검색에서 기록한 구독 이름이에요.
예:
CREATE NOTIFICATION INTEGRATION my_notification_int
TYPE = QUEUE
NOTIFICATION_PROVIDER = GCP_PUBSUB
ENABLED = true
GCP_PUBSUB_SUBSCRIPTION_NAME = 'projects/project-1234/subscriptions/sub2';
Step 2: Snowflake에 Pub/Sub 구독 접근 부여
- DESCRIBE INTEGRATION 명령을 실행해 Snowflake 서비스 계정 ID를 검색해요:
DESC NOTIFICATION INTEGRATION <integration_name>;
여기서:
integration_name은 Step 1: Snowflake에서 알림 통합 생성에서 만든 통합의 이름이에요.
예:
DESC NOTIFICATION INTEGRATION my_notification_int;
- GCP_PUBSUB_SERVICE_ACCOUNT 컬럼의 서비스 계정 이름을 기록해요. 형식은 다음과 같아요:
<service_account>@<project_id>.iam.gserviceaccount.com
- 프로젝트 편집자로 Google Cloud Platform 콘솔에 로그인해요.
- 홈 대시보드에서 Big Data » Pub/Sub » Subscriptions를 선택해요.
- 접근을 구성할 구독을 선택해요.
- 오른쪽 위 모서리의 SHOW INFO PANEL을 클릭해요. 구독의 정보 패널이 나와요.
- ADD PRINCIPAL 버튼을 클릭해요.
- New principals 필드에서 기록한 서비스 계정 이름을 검색해요.
- Select a role 드롭다운에서 Pub/Sub Subscriber를 선택해요.
- Save 버튼을 클릭해요. 서비스 계정 이름이 정보 패널의 Pub/Sub Subscriber 역할 드롭다운에 추가돼요.
- Cloud Console의 Dashboard 페이지로 이동해 드롭다운 목록에서 프로젝트를 선택해요.
- ADD PEOPLE TO THIS PROJECT 버튼을 클릭해요.
- 기록한 서비스 계정 이름을 추가해요.
- Select a role 드롭다운에서 Monitoring Viewer를 선택해요.
- Save 버튼을 클릭해요. 서비스 계정 이름이 Monitoring Viewer 역할에 추가돼요.
Step 3: 디렉터리 테이블이 포함된 스테이지 생성
CREATE STAGE 명령으로 GCS 버킷을 참조하는 외부 스테이지를 만들어요. Snowflake가 스테이징된 데이터 파일을 디렉터리 테이블 메타데이터로 읽어요. 또는 기존 외부 스테이지를 사용할 수 있어요.
Note
- 클라우드 저장소 위치에 대한 안전한 접근을 구성하려면 Cloud Storage에 대한 안전한 접근 구성을 참고해요(이 주제에서).
- CREATE STAGE 문에서 저장 통합을 참조하려면 역할이 저장 통합 객체에 대한 USAGE 권한이 있어야 해요.
-- External stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <external_stage_name>
<cloud_storage_access_settings>
[ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
[ directoryTable ]
[ COPY_OPTIONS = ( copyOptions ) ]
[ COMMENT = '<string_literal>' ]
여기서:
directoryTable ::=
[ DIRECTORY = ( ENABLE = { TRUE | FALSE }
[ AUTO_REFRESH = { TRUE | FALSE } ]
[ NOTIFICATION_INTEGRATION = '<notification_integration_name>' ] ) ]
디렉터리 테이블 파라미터(directoryTable)
ENABLE = { TRUE | FALSE }
스테이지에 디렉터리 테이블을 추가할지 여부를 지정해요. 값이 TRUE이면 스테이지와 함께 디렉터리 테이블이 생성돼요.
기본값: FALSE
AUTO_REFRESH = { TRUE | FALSE }
URL 값에 지정된 명명된 외부 스테이지에 새 데이터 파일이나 업데이트된 데이터 파일이 있을 때 Snowflake가 디렉터리 테이블 메타데이터의 자동 새로 고침 트리거를 활성화할지 여부를 지정해요.
TRUE
Snowflake가 디렉터리 테이블 메타데이터의 자동 새로 고침 트리거를 활성화해요.
FALSE
Snowflake가 디렉터리 테이블 메타데이터의 자동 새로 고침 트리거를 활성화하지 않아요. ALTER STAGE … REFRESH로 디렉터리 테이블 메타데이터를 주기적으로 수동으로 새로 고쳐 스테이지 경로의 현재 파일 목록과 동기화해야 해요.
기본값: FALSE
NOTIFICATION_INTEGRATION = '<notification_integration_name>'
Pub/Sub 알림으로 디렉터리 테이블 메타데이터를 자동으로 새로 고치는 데 사용되는 알림 통합의 이름을 지정해요. 알림 통합은 Snowflake와 타사 클라우드 메시지 큐 서비스 사이의 인터페이스를 제공하는 Snowflake 객체예요.
통합 이름은 모두 대문자로 제공해야 해요.
다음 예는 사용자 세션의 활성 스키마에 mystage라는 스테이지를 만들어요. 클라우드 저장소 URL에는 files 경로가 포함돼요. 스테이지는 my_storage_int라는 저장 통합을 참조해요.
NOTIFICATION_INTEGRATION 파라미터는 Step 1: Snowflake에서 알림 통합 생성에서 만든 my_notification_int 통합을 참조해요:
USE SCHEMA mydb.public;
CREATE STAGE mystage
URL='gcs://mybucket/files/'
STORAGE_INTEGRATION = my_storage_int
DIRECTORY = (
ENABLE = true
AUTO_REFRESH = true
NOTIFICATION_INTEGRATION = 'MY_NOTIFICATION_INT'
);
Note
- URL 값의 저장 위치는 앞 슬래시(
/)로 끝나야 해요. - 통합 이름은 모두 대문자로 제공해야 해요.
새 데이터 파일이나 업데이트된 데이터 파일이 클라우드 저장소 위치에 추가되면 이벤트 알림이 Snowflake에 그것들을 디렉터리 테이블 메타데이터로 스캔하도록 알려요.
Step 4: 디렉터리 테이블 메타데이터를 수동으로 새로 고침
디렉터리 테이블의 메타데이터를 ALTER STAGE 명령으로 수동으로 새로 고쳐요.
구문
ALTER STAGE [ IF EXISTS ] <name> REFRESH [ SUBPATH = '<relative-path>' ]
여기서:
REFRESH
디렉터리 테이블 정의에서 참조된 스테이징된 데이터 파일에 접근하고 테이블 메타데이터를 업데이트해요.
- 경로의 새 파일이 테이블 메타데이터에 추가돼요.
- 경로의 파일 변경이 테이블 메타데이터에서 업데이트돼요.
- 경로에 더 이상 없는 파일이 테이블 메타데이터에서 제거돼요.
현재 이 명령은 파일이 스테이지에 추가, 업데이트, 삭제될 때마다 실행해야 해요. 이 단계는 디렉터리 테이블의 스테이지 정의에서 메타데이터를 최신 관련 파일 집합과 동기화해요.
SUBPATH = '<relative-path>'
선택적으로 상대 경로를 지정해 데이터 파일의 특정 부분집합에 대한 메타데이터를 새로 고쳐요.
예
mystage라는 스테이지의 디렉터리 테이블 메타데이터를 수동으로 새로 고쳐요:
ALTER STAGE mystage REFRESH;
Important
디렉터리 테이블이 생성된 후 이 단계가 적어도 한 번 성공적으로 완료되지 않으면, 알림 이벤트가 디렉터리 테이블 메타데이터를 처음으로 자동 새로 고침을 트리거할 때까지 디렉터리 테이블을 쿼리해도 결과가 반환되지 않아요.
Step 5: 보안 구성
디렉터리 테이블을 쿼리하는 데 사용될 각 추가 역할에 대해 GRANT
| 객체 | 권한 | 참고 |
|---|---|---|
| 데이터베이스 | USAGE | |
| 스키마 | USAGE | |
| 명명된 스테이지 | USAGE, READ | |
| 명명된 파일 형식 | USAGE | 선택 사항; 만든 스테이지가 명명된 파일 형식을 참조하는 경우에만 필요. |
더 알아보기 (Learn more)
- Automated directory table metadata refreshes — 자동 새로 고침
- Directory tables — 디렉터리 테이블
- CREATE NOTIFICATION INTEGRATION — 알림 통합 생성
- CREATE STAGE — 스테이지 생성