Refresh directory tables automatically for Amazon S3

Refresh directory tables automatically for Amazon S3 (Amazon S3용 디렉터리 테이블 자동 새로 고침)

이 주제는 외부 스테이지에 디렉터리 테이블을 만들고 Amazon SQS(Simple Queue Service) 알림을 사용해 S3 버킷에 대한 디렉터리 테이블 메타데이터를 자동으로 새로 고치는 지침을 제공해요. 이 작업은 다음이 발생할 때 외부 스테이지·경로의 최신 관련 파일 집합과 메타데이터를 동기화해요.

출처: Snowflake Documentation

본문

경로의 새 파일이 테이블 메타데이터에 추가돼요.
경로의 파일 변경이 테이블 메타데이터에서 업데이트돼요.
경로에 더 이상 없는 파일이 테이블 메타데이터에서 제거돼요.

Note

이 주제의 작업을 수행하려면 스키마에 대한 CREATE STAGE 권한이 있는 역할을 사용해야 해요.
또한 AWS에 대한 관리자 접근이 있어야 해요. AWS 관리자가 아니라면 AWS 이벤트 알림을 구성하는 데 필요한 단계를 완료하도록 AWS 관리자에게 요청해요.
Snowflake는 비용, 이벤트 노이즈, 지연 시간을 줄이기 위해 디렉터리 테이블에 지원되는 이벤트만 보낼 것을 권장해요.

Amazon SQS를 사용한 디렉터리 테이블 자동 새로 고침의 제한 사항

VPS(Virtual Private Snowflake) 및 AWS PrivateLink 고객: VPC(VPS 포함) 내의 AWS 서비스가 SQS와 통신할 수 있지만, 이 트래픽은 VPC 내부에 있지 않아 VPC로 보호되지 않아요.
SQS 알림은 모니터링되는 S3 버킷에 새 파일이 도착해 로드할 준비가 되었을 때 Snowflake에 알려 줘요. SQS 알림에는 S3 이벤트와 파일 이름 목록이 포함돼요. 파일의 실제 데이터는 포함되지 않아요.

클라우드 플랫폼 지원

S3 이벤트 메시지를 사용한 자동 새로 고침 트리거는 지원 클라우드 플랫폼 중 어느 곳에 호스팅된 Snowflake 계정에서도 지원돼요.

클라우드 저장소에 대한 안전한 접근 구성

Note

데이터 파일을 저장하는 S3 버킷에 대한 안전한 접근을 이미 구성했다면 이 섹션을 건너뛸 수 있어요.

이 섹션은 클라우드 저장소에 대한 인증 책임을 Snowflake 신원 및 접근 관리(IAM) 엔티티로 위임하도록 Snowflake 저장 통합 객체를 구성하는 방법을 설명해요.

Note

이 옵션을 적극 권장해요. 클라우드 저장소 접근 시 IAM 자격 증명을 제공할 필요가 없어져요. 추가 저장소 접근 옵션은 Amazon S3에 대한 안전한 접근 구성을 참고해요.

이 섹션은 저장 통합을 사용해 Snowflake가 외부(즉, S3) 스테이지에서 참조되는 Amazon S3 버킷에서 데이터를 읽고 쓰게 하는 방법을 설명해요. 통합은 시크릿 키나 접근 토큰 같은 명시적 클라우드 공급자 자격 증명을 전달할 필요가 없게 하는 명명된 일급(first-class) Snowflake 객체예요. 통합 객체는 AWS 신원 및 접근 관리(IAM) 사용자 ID를 저장해요. 조직의 관리자가 AWS 계정에서 통합 IAM 사용자 권한을 부여해요.

통합은 또한 사용자가 통합을 사용하는 외부 스테이지를 만들 때 지정할 수 있는 위치를 제한하는 버킷(및 선택적 경로)을 나열할 수 있어요.

Note

이 섹션의 지침을 완료하려면 IAM 정책과 역할을 만들고 관리할 AWS 권한이 필요해요. AWS 관리자가 아니라면 이 작업을 수행하도록 AWS 관리자에게 요청해요.
현재 정부 리전의 S3 저장소에 저장 통합을 사용해 접근하는 것은 같은 정부 리전의 AWS에 호스팅된 Snowflake 계정으로 제한된다는 점을 주목해요. 정부 리전 밖에 호스팅된 계정에서 직접 자격 증명을 사용해 S3 저장소에 접근하는 것은 지원돼요.

다음 다이어그램은 S3 스테이지의 통합 흐름을 보여 줘요.

외부(즉, S3) 스테이지가 정의에서 저장 통합 객체를 참조해요.
Snowflake가 저장 통합을 계정용으로 만들어진 S3 IAM 사용자와 자동으로 연결해요. Snowflake 계정의 모든 S3 저장 통합이 참조하는 단일 IAM 사용자를 만들어요.
조직의 AWS 관리자가 스테이지 정의에서 참조된 버킷에 접근할 수 있도록 IAM 사용자에게 권한을 부여해요. 여러 외부 스테이지 객체가 다른 버킷·경로를 참조하고 인증에 같은 저장 통합을 사용할 수 있다는 점을 주목해요.

사용자가 스테이지에서 데이터를 로드하거나 언로드할 때 Snowflake는 버킷에 대해 IAM 사용자에게 부여된 권한을 확인한 뒤 접근을 허용하거나 거부해요.

Step 1: S3 버킷에 대한 접근 권한 구성

AWS 접근 제어 요구 사항

Snowflake는 폴더(및 하위 폴더)의 파일에 접근하려면 S3 버킷과 폴더에 대한 다음 권한이 필요해요.

s3:GetBucketLocation
s3:GetObject
s3:GetObjectVersion
s3:ListBucket

모범 사례로 Snowflake는 S3 버킷에 대한 Snowflake 접근용 IAM 정책을 만들 것을 권장해요. 그런 다음 정책을 역할에 연결하고 AWS가 역할에 대해 생성한 보안 자격 증명을 사용해 버킷의 파일에 접근할 수 있어요.

IAM 정책 생성

다음 단계별 지침은 AWS Management Console에서 Snowflake가 S3 버킷에 접근할 수 있도록 접근 권한을 구성하는 방법을 설명해요.

AWS Management Console에 로그인해요.
홈 대시보드에서 IAM을 검색해 선택해요.
왼쪽 탐색 창에서 Account settings를 선택해요.
Endpoints 목록의 Security Token Service (STS) 아래에서 Snowflake 계정이 위치한 리전을 찾아요. STS status가 비활성화되어 있으면 토글을 Active로 옮겨요.
왼쪽 탐색 창에서 Policies를 선택해요.
Create Policy를 선택해요.
Policy editor에서 JSON을 선택해요.
Snowflake가 S3 버킷과 폴더에 접근할 수 있게 하는 정책 문서를 추가해요.

다음 정책(JSON 형식)은 단일 버킷과 폴더 경로를 사용해 데이터를 로드하거나 언로드하는 데 필요한 권한을 Snowflake에 제공해요.

정책 편집기에 텍스트를 복사해 붙여넣어요:

Note

*bucket*과 *prefix*를 실제 버킷 이름과 폴더 경로 프리픽스로 바꿔야 해요.
정부 리전의 버킷에 대한 ARN(Amazon Resource Name)은 arn:aws-us-gov:s3::: 프리픽스가 있어요.

{
 "Version": "2012-10-17",
 "Statement": [
     {
         "Effect": "Allow",
         "Action": [
           "s3:GetObject",
           "s3:GetObjectVersion"
         ],
         "Resource": "arn:aws:s3:::<bucket>/<prefix>/*"
     },
     {
         "Effect": "Allow",
         "Action": [
             "s3:ListBucket",
             "s3:GetBucketLocation"
         ],
         "Resource": "arn:aws:s3:::<bucket>",
         "Condition": {
             "StringLike": {
                 "s3:prefix": [
                     "<prefix>/*"
                 ]
             }
         }
     }
 ]
}

Note

s3:prefix: 조건을 ["*"]로 설정하면 지정된 버킷의 모든 프리픽스에, ["<path>/*"]로 설정하면 버킷의 경로에 접근을 부여해요.

AWS 정책은 다양한 보안 사용 사례를 지원한다는 점을 주목해요.

Next를 선택해요.
Policy name(예: snowflake_access)과 선택적 Description을 입력해요.
Create policy를 선택해요.

Step 2: AWS에서 IAM 역할 생성

AWS Management Console에서 Snowflake 접근 권한을 구성하려면:

IAM(Identity and Access Management) 대시보드의 왼쪽 탐색 창에서 Roles를 선택해요.
Create role을 선택해요.
신뢰할 수 있는 엔티티 유형으로 AWS account를 선택해요.
Another AWS account를 선택해요.
Account ID 필드에 자신의 AWS 계정 ID를 임시로 입력해요. 나중에 신뢰 관계를 수정하고 Snowflake에 접근을 부여해요.
Require external ID 옵션을 선택해요. 외부 ID는 Snowflake 같은 제3자에게 AWS 리소스(예: S3 버킷)에 대한 접근을 부여하는 데 사용돼요. 0000 같은 자리 표시자 ID를 입력해요. 이후 단계에서 IAM 역할의 신뢰 관계를 수정하고 저장 통합의 외부 ID를 지정할 거예요.
Next를 선택해요.
Step 1: S3 버킷에 대한 접근 권한 구성에서 만든 정책을 선택해요(이 주제에서).
Next를 선택해요.
역할의 이름과 설명을 입력한 다음 Create role을 선택해요.

이제 버킷용 IAM 정책을 만들고, IAM 역할을 만들고, 정책을 역할에 연결했어요.

역할 요약 페이지에서 Role ARN 값을 찾아 기록해요. 다음 단계에서 이 역할을 참조하는 Snowflake 통합을 만들 거예요.

Note

Snowflake는 임시 자격 증명을 60분 만료 시간을 초과할 수 없는 기간 동안 캐시해요. Snowflake에서 접근을 회수하면 캐시가 만료될 때까지 사용자가 클라우드 저장 위치의 파일을 나열하고 데이터에 접근할 수 있을 수 있어요.

Step 3: Snowflake에서 클라우드 저장 통합 생성

CREATE STORAGE INTEGRATION 명령으로 저장 통합을 만들어요. 저장 통합은 S3 클라우드 저장소용으로 생성된 신원 및 접근 관리(IAM) 사용자와 함께 선택적 허용·차단 저장 위치(즉, 버킷) 집합을 저장하는 Snowflake 객체예요. 조직의 클라우드 공급자 관리자가 생성된 사용자에 저장 위치에 대한 권한을 부여해요. 이 옵션은 사용자가 스테이지를 만들거나 데이터를 로드할 때 자격 증명을 제공하지 않게 해줘요.

단일 저장 통합은 여러 외부(즉, S3) 스테이지를 지원할 수 있어요. 스테이지 정의의 URL은 STORAGE_ALLOWED_LOCATIONS 파라미터에 지정된 S3 버킷(및 선택적 경로)과 일치해야 해요.

Note

계정 관리자(ACCOUNTADMIN 역할을 가진 사용자) 또는 전역 CREATE INTEGRATION 권한이 있는 역할만 이 SQL 명령을 실행할 수 있어요.

CREATE STORAGE INTEGRATION <integration_name>
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  ENABLED = TRUE
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  STORAGE_ALLOWED_LOCATIONS = ('<protocol>://<bucket>/<path>/', '<protocol>://<bucket>/<path>/')
  [ STORAGE_BLOCKED_LOCATIONS = ('<protocol>://<bucket>/<path>/', '<protocol>://<bucket>/<path>/') ]

여기서:

integration_name은 새 통합의 이름이에요.
iam_role은 Step 2: AWS에서 IAM 역할 생성에서 만든 역할의 ARN(Amazon Resource Name)이에요(이 주제에서).
protocol은 다음 중 하나예요.
- s3는 중국 외부의 공용 AWS 리전에 있는 S3 저장소를 가리켜요.
- s3china는 중국의 공용 AWS 리전에 있는 S3 저장소를 가리켜요.
- s3gov는 정부 리전의 S3 저장소를 가리켜요.
bucket은 데이터 파일을 저장하는 S3 버킷의 이름(예: mybucket)이에요. 필수 STORAGE_ALLOWED_LOCATIONS 파라미터와 선택적 STORAGE_BLOCKED_LOCATIONS 파라미터는 이 통합을 참조하는 스테이지가 생성되거나 수정될 때 각각 이러한 버킷에 대한 접근을 제한하거나 차단해요.
path는 버킷의 객체에 대한 세밀한 제어를 제공하는 데 사용할 수 있는 선택적 경로예요.

다음 예는 계정의 모든 버킷에 대한 접근을 허용하지만 정의된 sensitivedata 폴더에 대한 접근을 차단하는 통합을 만들어요.

이 통합을 사용하는 추가 외부 스테이지가 허용된 버킷·경로를 참조할 수 있어요:

CREATE STORAGE INTEGRATION s3_int
  TYPE = EXTERNAL_STAGE
  STORAGE_PROVIDER = 'S3'
  ENABLED = TRUE
  STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::001234567890:role/myrole'
  STORAGE_ALLOWED_LOCATIONS = ('*')
  STORAGE_BLOCKED_LOCATIONS = ('s3://mybucket1/mypath1/sensitivedata/', 's3://mybucket2/mypath2/sensitivedata/');

Note

선택적으로 STORAGE_AWS_EXTERNAL_ID 파라미터로 자신의 외부 ID를 지정할 수 있어요. 여러 외부 볼륨 및/또는 저장 통합에 걸쳐 같은 외부 ID를 사용하려면 이 옵션을 선택할 수 있어요.

Step 4: Snowflake 계정의 AWS IAM 사용자 검색

Snowflake 계정용으로 자동 생성된 IAM 사용자의 ARN을 검색하려면 DESCRIBE INTEGRATION을 사용해요.

DESC INTEGRATION <integration_name>;

여기서:

integration_name은 Step 3: Snowflake에서 클라우드 저장 통합 생성에서 만든 통합의 이름이에요(이 주제에서).

예:

DESC INTEGRATION s3_int;

+---------------------------+---------------+--------------------------------------------------------------------------------+------------------+
| property                  | property_type | property_value                                                                 | property_default |
+---------------------------+---------------+--------------------------------------------------------------------------------+------------------+
| ENABLED                   | Boolean       | true                                                                           | false            |
| STORAGE_ALLOWED_LOCATIONS | List          | s3://mybucket1/mypath1/,s3://mybucket2/mypath2/                                | []               |
| STORAGE_BLOCKED_LOCATIONS | List          | s3://mybucket1/mypath1/sensitivedata/,s3://mybucket2/mypath2/sensitivedata/    | []               |
| STORAGE_AWS_IAM_USER_ARN  | String        | arn:aws:iam::123456789001:user/abc1-b-self1234                                 |                  |
| STORAGE_AWS_ROLE_ARN      | String        | arn:aws:iam::001234567890:role/myrole                                          |                  |
| STORAGE_AWS_EXTERNAL_ID   | String        | MYACCOUNT_SFCRole=2_a123456/s0aBCDEfGHIJklmNoPq=                               |                  |
+---------------------------+---------------+--------------------------------------------------------------------------------+------------------+

다음 속성의 값을 기록해요.

속성	설명
STORAGE_AWS_IAM_USER_ARN	Snowflake 계정용으로 만들어진 AWS IAM 사용자(예: arn:aws:iam::123456789001:user/abc1-b-self1234). Snowflake는 전체 Snowflake 계정에 대해 단일 IAM 사용자를 프로비저닝해요. 계정의 모든 S3 저장 통합이 그 IAM 사용자를 사용해요.
STORAGE_AWS_EXTERNAL_ID	Snowflake가 AWS와 신뢰 관계를 설정하는 데 사용하는 외부 ID. 저장 통합을 만들 때 외부 ID(STORAGE_AWS_EXTERNAL_ID)를 지정하지 않았다면 Snowflake가 사용할 ID를 생성해요.

다음 섹션에서 이 값들을 제공해요.

Step 5: 버킷 객체에 접근할 수 있도록 IAM 사용자에게 권한 부여

다음 단계별 지침은 S3 버킷을 사용해 데이터를 로드·언로드할 수 있도록 AWS Management Console에서 Snowflake에 IAM 접근 권한을 구성하는 방법을 설명해요.

AWS Management Console에 로그인해요.
IAM을 선택해요.
왼쪽 탐색 창에서 Roles를 선택해요.
Step 2: AWS에서 IAM 역할 생성에서 만든 역할을 선택해요(이 주제에서).
Trust relationships 탭을 선택해요.
Edit trust policy를 선택해요.
Step 4: Snowflake 계정의 AWS IAM 사용자 검색에서 기록한 DESC STORAGE INTEGRATION 출력 값으로 정책 문서를 수정해요(이 주제에서).

IAM 역할용 정책 문서

{
  "Version": "2012-10-17",
  "Statement": [
 {
   "Sid": "",
   "Effect": "Allow",
   "Principal": {
     "AWS": "<snowflake_user_arn>"
   },
   "Action": "sts:AssumeRole",
   "Condition": {
     "StringEquals": {
       "sts:ExternalId": "<snowflake_external_id>"
     }
   }
 }
  ]
}

여기서:

snowflake_user_arn은 기록한 STORAGE_AWS_IAM_USER_ARN 값이에요.
snowflake_external_id는 기록한 STORAGE_AWS_EXTERNAL_ID 값이에요.

이 예에서 snowflake_external_id 값은 MYACCOUNT_SFCRole=2_a123456/s0aBCDEfGHIJklmNoPq=예요.

Note

보안상의 이유로 새 저장 통합을 만들거나(CREATE OR REPLACE STORAGE INTEGRATION 구문으로 기존 저장 통합을 다시 만들되) 외부 ID를 지정하지 않으면 새 통합은 다른 외부 ID를 가지므로 신뢰 정책을 업데이트하지 않는 한 신뢰 관계를 해결할 수 없어요.

Update policy를 선택해 변경 사항을 저장해요.

Note

Snowflake는 임시 자격 증명을 60분 만료 시간을 초과할 수 없는 기간 동안 캐시해요. Snowflake에서 접근을 회수하면 캐시가 만료될 때까지 사용자가 클라우드 저장 위치의 파일을 나열하고 데이터를 로드할 수 있을 수 있어요.

Note

SYSTEM$VALIDATE_STORAGE_INTEGRATION 함수를 사용해 저장 통합 구성을 검증할 수 있어요.

올바른 옵션 결정

진행하기 전에 데이터 파일이 있는 S3 버킷의 대상 경로(또는 AWS 용어로 "프리픽스")에 대한 S3 이벤트 알림이 존재하는지 결정해요. AWS 규칙은 같은 경로에 대한 충돌하는 알림 생성을 금지해요.

Amazon SQS를 사용해 디렉터리 테이블 메타데이터 새로 고침을 자동화하는 다음 옵션이 지원돼요.

옵션 1. 새 S3 이벤트 알림: S3 버킷의 대상 경로에 대한 이벤트 알림을 만들어요. 이벤트 알림은 경로의 새 ·제거·수정 파일이 디렉터리 테이블 메타데이터 새로 고침을 필요로 할 때 SQS 큐를 통해 Snowflake에 알려 줘요.

Important

S3 버킷에 충돌하는 이벤트 알림이 존재하면 대신 옵션 2를 사용해요.

옵션 2. 기존 이벤트 알림: Amazon Simple Notification Service (SNS)를 브로드캐스터로 구성해 주어진 경로에 대한 알림을 디렉터리 테이블 새로 고침 자동화용 Snowflake SQS 큐를 포함한 여러 엔드포인트(또는 "구독자", 예: SQS 큐 또는 AWS Lambda 워크로드)와 공유해요. SNS가 게시한 S3 이벤트 알림이 SQS 큐를 통해 경로의 파일 변경을 Snowflake에 알려 줘요.

Note

Stage, pipe, load history 복제를 사용할 계획이라면 이 옵션을 권장해요. 복제 또는 장애 조치 그룹을 만든 후 옵션 1에서 옵션 2로 마이그레이션할 수도 있어요. 자세한 내용은 Amazon Simple Notification Service(SNS)로 마이그레이션을 참고해요.

옵션 1: 새 S3 이벤트 알림 생성

이 섹션은 Amazon SQS(Simple Queue Service) 알림을 사용해 S3 버킷에 대한 디렉터리 테이블 메타데이터를 자동으로 새로 고치는 가장 일반적인 옵션을 설명해요. 단계는 데이터 파일이 저장된 S3 버킷의 대상 경로(또는 AWS 용어로 "프리픽스")에 대한 이벤트 알림을 만드는 방법을 설명해요.

Important

S3 버킷에 충돌하는 이벤트 알림이 존재하면 옵션 2: Amazon SNS 구성을 대신 사용해요(이 주제에서). AWS 규칙은 같은 대상 경로에 대한 충돌하는 알림 생성을 금지해요.

Step 1: 디렉터리 테이블이 포함된 스테이지 생성

CREATE STAGE 명령으로 S3 버킷을 참조하는 외부 스테이지를 만들어요. Snowflake가 스테이징된 데이터 파일을 디렉터리 테이블 메타데이터로 읽어요. 또는 기존 외부 스테이지를 사용할 수 있어요.

Note

클라우드 저장소 위치에 대한 안전한 접근을 구성하려면 클라우드 저장소에 대한 안전한 접근 구성을 참고해요(이 주제에서).
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>' ]

Note

URL 값의 저장 위치는 앞 슬래시(/)로 끝나야 해요.

여기서:

directoryTable (for Amazon S3) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ AUTO_REFRESH = { TRUE | FALSE } ] ) ]

디렉터리 테이블 파라미터(directoryTable)

ENABLE = { TRUE | FALSE }

스테이지에 디렉터리 테이블을 추가할지 여부를 지정해요. 값이 TRUE이면 스테이지와 함께 디렉터리 테이블이 생성돼요.

기본값: FALSE

AUTO_REFRESH = { TRUE | FALSE }

URL 값에 지정된 명명된 외부 스테이지에 새 데이터 파일이나 업데이트된 데이터 파일이 있을 때 Snowflake가 디렉터리 테이블 메타데이터의 자동 새로 고침 트리거를 활성화할지 여부를 지정해요.

TRUE

Snowflake가 디렉터리 테이블 메타데이터의 자동 새로 고침 트리거를 활성화해요.

FALSE

Snowflake가 디렉터리 테이블 메타데이터의 자동 새로 고침 트리거를 활성화하지 않아요. ALTER STAGE … REFRESH로 디렉터리 테이블 메타데이터를 주기적으로 수동으로 새로 고쳐 스테이지 경로의 현재 파일 목록과 동기화해야 해요.

기본값: FALSE

다음 예는 사용자 세션의 활성 스키마에 mystage라는 스테이지를 만들어요. 클라우드 저장소 URL에는 files 경로가 포함돼요. 스테이지는 my_storage_int라는 저장 통합을 참조해요.

USE SCHEMA mydb.public;

CREATE STAGE mystage
  URL='s3://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (
    ENABLE = true
    AUTO_REFRESH = true
  );

새 데이터 파일이나 업데이트된 데이터 파일이 클라우드 저장소 위치에 추가되면 이벤트 알림이 Snowflake에 그것들을 디렉터리 테이블 메타데이터로 스캔하도록 알려요.

Step 2: 이벤트 알림 구성

새 데이터나 업데이트된 데이터를 디렉터리 테이블 메타데이터로 읽을 수 있게 되었을 때 Snowflake에 알리도록 S3 버킷에 대한 이벤트 알림을 구성해요. 자동 새로 고침 기능은 SQS 큐에 의존해 S3에서 Snowflake로 이벤트 알림을 전달해요.

사용 편의를 위해 이 SQS 큐는 Snowflake가 생성·관리해요. DESCRIBE STAGE 명령 출력이 SQS 큐의 ARN(Amazon Resource Name)을 표시해요.

DESCRIBE STAGE 명령을 실행해요:

DESC STAGE <stage_name>;

예:

DESC STAGE mystage;

directory_notification_channel 필드에서 디렉터리 테이블용 SQS 큐의 ARN을 기록해요. ARN을 편리한 위치에 복사해요.

Note

AWS 지침에 따라 Snowflake는 AWS S3 리전당 하나 이하의 SQS 큐를 지정해요. 이 SQS 큐는 같은 AWS 계정의 여러 버킷 간에 공유될 수 있어요. 이 SQS 큐는 같은 S3 버킷에서 데이터 파일을 읽는 모든 디렉터리 테이블에 대한 알림을 조정해요. 새 파일이나 수정된 데이터 파일이 버킷에 업로드되면 스테이지 디렉터리 경로와 일치하는 모든 디렉터리 테이블 정의가 파일 세부 정보를 메타데이터로 읽어요.

AWS Management Console에 로그인해요.
Amazon S3 문서에 제공된 지침을 사용해 S3 버킷에 대한 이벤트 알림을 구성해요. 다음 필드를 채워요.
- Name: 이벤트 알림의 이름(예: Auto-ingest Snowflake).
- Events: ObjectCreate (All) 및 ObjectRemoved 옵션을 선택해요.
- Send to: 드롭다운 목록에서 SQS Queue를 선택해요.
- SQS: 드롭다운 목록에서 Add SQS queue ARN을 선택해요.
- SQS queue ARN: DESC STAGE 출력의 SQS 큐 이름을 붙여넣어요.

Note

이 지침은 전체 S3 버킷의 활동을 모니터링하는 단일 이벤트 알림을 만들어요. 이것이 가장 간단한 접근 방식이에요. 이 알림은 S3 버킷 디렉터리에서 더 세분화된 수준으로 구성된 모든 디렉터리 테이블을 처리해요.

또는 위 단계에서 하나 이상의 경로 및/또는 파일 확장자(또는 AWS 용어로 프리픽스 및 접미사)를 구성해 이벤트 활동을 필터링할 수 있어요. 지침은 관련 AWS 문서 주제의 객체 키 이름 필터링 정보를 참고해요. 알림이 모니터링하길 원하는 각 추가 경로나 파일 확장자에 대해 이 단계를 반복해요.

AWS는 이러한 알림 큐 구성 수를 S3 버킷당 최대 100개로 제한한다는 점을 주목해요.

또한 AWS는 같은 S3 버킷에 대해 중첩되는 큐 구성(이벤트 알림 간)을 허용하지 않는다는 점을 주목해요. 예를 들어 s3://mybucket/files/path1에 대해 기존 알림이 구성되어 있다면 s3://mybucket/files 같은 더 높은 수준에서 다른 알림을 만들 수 없고 그 반대도 마찬가지예요.

자동 새로 고침이 있는 외부 스테이지가 이제 구성됐어요!

새 데이터 파일이나 업데이트된 데이터 파일이 S3 버킷에 추가되면 이벤트 알림이 Snowflake에 그것들을 디렉터리 테이블 메타데이터로 스캔하도록 알려요.

Step 3: 디렉터리 테이블 메타데이터를 수동으로 새로 고침

디렉터리 테이블의 메타데이터를 ALTER STAGE 명령으로 수동으로 새로 고쳐요.

ALTER STAGE [ IF EXISTS ] <name> REFRESH [ SUBPATH = '<relative-path>' ]

여기서:

REFRESH

디렉터리 테이블 정의에서 참조된 스테이징된 데이터 파일에 접근하고 테이블 메타데이터를 업데이트해요.

경로의 새 파일이 테이블 메타데이터에 추가돼요.
경로의 파일 변경이 테이블 메타데이터에서 업데이트돼요.
경로에 더 이상 없는 파일이 테이블 메타데이터에서 제거돼요.

현재 이 명령은 파일이 스테이지에 추가, 업데이트, 삭제될 때마다 실행해야 해요. 이 단계는 디렉터리 테이블의 스테이지 정의에서 메타데이터를 최신 관련 파일 집합과 동기화해요.

SUBPATH = '<relative-path>'

선택적으로 상대 경로를 지정해 데이터 파일의 특정 부분집합에 대한 메타데이터를 새로 고쳐요.

예를 들어 mystage라는 스테이지의 디렉터리 테이블 메타데이터를 수동으로 새로 고쳐요:

ALTER STAGE mystage REFRESH;

Important

디렉터리 테이블이 생성된 후 이 단계가 적어도 한 번 성공적으로 완료되지 않으면, 알림 이벤트가 디렉터리 테이블 메타데이터를 처음으로 자동 새로 고침을 트리거할 때까지 디렉터리 테이블을 쿼리해도 결과가 반환되지 않아요.

Step 4: 보안 구성

디렉터리 테이블을 쿼리하는 데 사용될 각 추가 역할에 대해 GRANT … TO ROLE을 사용해 다양한 객체(즉, 데이터베이스(들), 스키마(들), 스테이지, 테이블)에 충분한 접근 제어 권한을 부여해요.

객체	권한	참고
데이터베이스	USAGE
스키마	USAGE
명명된 스테이지	USAGE, READ
명명된 파일 형식	USAGE

이 섹션은 Amazon SQS(Simple Queue Service) 알림을 사용해 S3 버킷에 대한 디렉터리 테이블 메타데이터 새로 고침을 자동으로 트리거하는 방법을 설명해요. 단계는 Amazon Simple Notification Service(SNS)를 브로드캐스터로 구성해 S3 버킷의 이벤트 알림을 디렉터리 테이블 새로 고침 자동화용 Snowflake SQS 큐를 포함한 여러 구독자(예: SQS 큐 또는 AWS Lambda 워크로드)에게 게시하는 방법을 설명해요.

Note

이 지침은 데이터 파일이 있는 S3 버킷의 대상 경로에 대한 이벤트 알림이 존재한다고 가정해요. 이벤트 알림이 없으면:

옵션 1: 새 S3 이벤트 알림 생성을 대신 따르세요(이 주제에서).
또는 S3 버킷에 대한 이벤트 알림을 만든 다음 이 주제의 지침을 진행하세요. 정보는 Amazon S3 문서를 참고해요.

S3 버킷의 Snowflake 스테이지 위치에 대한 모든 메시지를 처리하도록 AWS 계정에 SNS 토픽을 만들어요.
S3 이벤트 알림에 대한 대상 목적지(예: 다른 SQS 큐 또는 AWS Lambda 워크로드)를 이 토픽에 구독해요. SNS는 토픽의 모든 구독자에게 버킷에 대한 이벤트 알림을 게시해요.

지침은 SNS 문서를 참고해요.

Step 1: Snowflake SQS 큐를 SNS 토픽에 구독

AWS Management Console에 로그인해요.
홈 대시보드에서 Simple Notification Service(SNS)를 선택해요.
왼쪽 탐색 창에서 Topics를 선택해요.
S3 버킷의 토픽을 찾아요. 토픽 ARN을 기록해요.
Snowflake 클라이언트로 SYSTEM$GET_AWS_SNS_IAM_POLICY 시스템 함수를 SNS 토픽 ARN으로 쿼리해요:

select system$get_aws_sns_iam_policy('<sns_topic_arn>');

함수는 Snowflake SQS 큐가 SNS 토픽에 구독할 권한을 부여하는 IAM 정책을 반환해요.

예:

select system$get_aws_sns_iam_policy('arn:aws:sns:us-west-2:001234567890:s3_mybucket');

+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| SYSTEM$GET_AWS_SNS_IAM_POLICY('ARN:AWS:SNS:US-WEST-2:001234567890:S3_MYBUCKET')                                                                                                                                                                   |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| {"Version":"2012-10-17","Statement":[{"Sid":"1","Effect":"Allow","Principal":{"AWS":"arn:aws:iam::123456789001:user/vj4g-a-abcd1234"},"Action":["sns:Subscribe"],"Resource":["arn:aws:sns:us-west-2:001234567890:s3_mybucket"]}]}                 |
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

AWS Management Console로 돌아가 왼쪽 탐색 창에서 Topics를 선택해요.
S3 버킷의 토픽을 선택하고 Edit 버튼을 클릭해요. Edit 페이지가 열려요.
Access policy - Optional을 클릭해 이 페이지의 해당 영역을 펼쳐요.
SYSTEM$GET_AWS_SNS_IAM_POLICY 함수 결과의 IAM 정책 추가분을 JSON 문서에 병합해요.

예:

원래 IAM 정책(축약):

{
  "Version":"2008-10-17",
  "Id":"__default_policy_ID",
  "Statement":[
  {
     "Sid":"__default_statement_ID",
     "Effect":"Allow",
     "Principal":{
        "AWS":"*"
     }
     ..
  }
]
 }

병합된 IAM 정책:

{
  "Version":"2008-10-17",
  "Id":"__default_policy_ID",
  "Statement":[
  {
     "Sid":"__default_statement_ID",
     "Effect":"Allow",
     "Principal":{
        "AWS":"*"
     }
     ..
  },
  {
     "Sid":"1",
     "Effect":"Allow",
     "Principal":{
       "AWS":"arn:aws:iam::123456789001:user/vj4g-a-abcd1234"
      },
      "Action":[
        "sns:Subscribe"
      ],
      "Resource":[
        "arn:aws:sns:us-west-2:001234567890:s3_mybucket"
      ]
  }
]
 }

S3이 버킷에 대한 이벤트 알림을 SNS 토픽에 게시할 수 있도록 추가 정책 부여를 추가해요.

예(SNS 토픽 ARN과 모든 지침에서 사용된 S3 버킷 사용):

{
 "Sid":"s3-event-notifier",
 "Effect":"Allow",
 "Principal":{
    "Service":"s3.amazonaws.com"
 },
 "Action":"SNS:Publish",
 "Resource":"arn:aws:sns:us-west-2:001234567890:s3_mybucket",
 "Condition":{
    "ArnLike":{
       "aws:SourceArn":"arn:aws:s3:*:*:s3_mybucket"
    }
 }
 }

병합된 IAM 정책:

{
  "Version":"2008-10-17",
  "Id":"__default_policy_ID",
  "Statement":[
  {
     "Sid":"__default_statement_ID",
     "Effect":"Allow",
     "Principal":{
        "AWS":"*"
     }
     ..
  },
  {
     "Sid":"1",
     "Effect":"Allow",
     "Principal":{
       "AWS":"arn:aws:iam::123456789001:user/vj4g-a-abcd1234"
      },
      "Action":[
        "sns:Subscribe"
      ],
      "Resource":[
        "arn:aws:sns:us-west-2:001234567890:s3_mybucket"
      ]
  },
  {
     "Sid":"s3-event-notifier",
     "Effect":"Allow",
     "Principal":{
        "Service":"s3.amazonaws.com"
     },
     "Action":"SNS:Publish",
     "Resource":"arn:aws:sns:us-west-2:001234567890:s3_mybucket",
     "Condition":{
        "ArnLike":{
           "aws:SourceArn":"arn:aws:s3:*:*:s3_mybucket"
        }
     }
   }
]
 }

Save changes를 클릭해요.

Step 2: 디렉터리 테이블이 포함된 스테이지 생성

Note

클라우드 저장소 위치에 대한 안전한 접근을 구성하려면 클라우드 저장소에 대한 안전한 접근 구성을 참고해요(이 주제에서).
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 (for Amazon S3) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ AUTO_REFRESH = { TRUE | FALSE } ]
                  [ AWS_SNS_TOPIC = '<sns_topic_arn>' ] ) ]

디렉터리 테이블 파라미터(directoryTable)

ENABLE = { TRUE | FALSE }

스테이지에 디렉터리 테이블을 추가할지 여부를 지정해요. 값이 TRUE이면 스테이지와 함께 디렉터리 테이블이 생성돼요.

기본값: FALSE

AUTO_REFRESH = { TRUE | FALSE }

TRUE

Snowflake가 디렉터리 테이블 메타데이터의 자동 새로 고침 트리거를 활성화해요.

FALSE

기본값: FALSE

Amazon S3

AWS_SNS_TOPIC = '<sns_topic_arn>'

S3 버킷용 SNS 토픽의 ARN을 지정해요. CREATE directory table 문이 Snowflake SQS 큐를 지정된 SNS 토픽에 구독해요.

USE SCHEMA mydb.public;

CREATE STAGE mystage
  URL='s3://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (
    ENABLE = true
    AUTO_REFRESH = true
    AWS_SNS_TOPIC = 'arn:aws:sns:us-west-2:001234567890:s3_mybucket'
  );

Step 3: 디렉터리 테이블 메타데이터를 수동으로 새로 고침

디렉터리 테이블의 메타데이터를 ALTER STAGE 명령으로 수동으로 새로 고쳐요.

ALTER STAGE [ IF EXISTS ] <name> REFRESH [ SUBPATH = '<relative-path>' ]

여기서:

REFRESH

디렉터리 테이블 정의에서 참조된 스테이징된 데이터 파일에 접근하고 테이블 메타데이터를 업데이트해요.

경로의 새 파일이 테이블 메타데이터에 추가돼요.
경로의 파일 변경이 테이블 메타데이터에서 업데이트돼요.
경로에 더 이상 없는 파일이 테이블 메타데이터에서 제거돼요.

SUBPATH = '<relative-path>'

선택적으로 상대 경로를 지정해 데이터 파일의 특정 부분집합에 대한 메타데이터를 새로 고쳐요.

예를 들어 mystage라는 스테이지의 디렉터리 테이블 메타데이터를 수동으로 새로 고쳐요:

ALTER STAGE mystage REFRESH;

Important

Step 4: 보안 구성

객체	권한	참고
데이터베이스	USAGE
스키마	USAGE
명명된 스테이지	USAGE, READ
명명된 파일 형식	USAGE

더 알아보기 (Learn more)

Automated directory table metadata refreshes — 자동 새로 고침
Directory tables — 디렉터리 테이블
SYSTEM$GET_AWS_SNS_IAM_POLICY — SNS IAM 정책 함수
CREATE STAGE — 스테이지 생성

Refresh directory tables automatically for Amazon S3