CREATE EXTERNAL VOLUME

계정에 Apache Iceberg™ 테이블용 새 외부 볼륨(external volume)을 만들거나 기존 외부 볼륨을 교체하는 명령이에요. 외부 볼륨은 클라우드 저장소 위치를 Iceberg 테이블에 연결해줘요.

출처: 문서

본문

외부 볼륨은 Iceberg 테이블의 데이터/메타데이터 파일이 저장되는 클라우드 저장소 위치를 정의해요.

구문 (Syntax)

CREATE [ OR REPLACE ] EXTERNAL VOLUME [IF NOT EXISTS]
  <name>
  STORAGE_LOCATIONS =
    (
      (
        NAME = '<storage_location_name>'
        { cloudProviderParams | s3CompatibleStorageParams }
      )
      [, (...), ...]
    )
  [ ALLOW_WRITES = { TRUE | FALSE }]
  [ COMMENT = '<string_literal>' ]

여기서:

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = '{ S3 | S3GOV }'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  STORAGE_BASE_URL = '<protocol>://<bucket>[/<path>/]'
  [ STORAGE_AWS_ACCESS_POINT_ARN = '<string>' ]
  [ STORAGE_AWS_EXTERNAL_ID = '<external_id>' ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_SSE_S3' ] |
              [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] |
              [ TYPE = 'NONE' ] ) ]
  [ USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } ]

cloudProviderParams (for Google Cloud Storage) ::=
  STORAGE_PROVIDER = 'GCS'
  STORAGE_BASE_URL = 'gcs://<bucket>[/<path>/]'
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] |
              [ TYPE = 'NONE' ] ) ]

cloudProviderParams (for Microsoft Azure) ::=
  STORAGE_PROVIDER = 'AZURE'
  AZURE_TENANT_ID = '<tenant_id>'
  STORAGE_BASE_URL = 'azure://...'
  [ USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } ]

s3CompatibleStorageParams ::=
  STORAGE_PROVIDER = 'S3COMPAT'
  STORAGE_BASE_URL = 's3compat://<bucket>[/<path>/]'
  CREDENTIALS = ( AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' )
  STORAGE_ENDPOINT = '<s3_api_compatible_endpoint>'

필수 매개변수

<name>: 외부 볼륨의 식별자(이름) 문자열이에요. 계정 내에서 고유해야 해요. 기본 문자로 시작해야 하며, 전체 식별자를 큰따옴표로 감싸지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object").
STORAGE_LOCATIONS = ( ( NAME = 'storage_location_name' { cloudProviderParams | s3CompatibleStorageParams } ) [, (...), ...] ): 서로 다른 리전 및 선택적으로 클라우드 플랫폼에 있는 명명된 클라우드 저장소 위치의 집합이에요. 각 외부 볼륨은 단일 활성 저장소 위치를 지원해요.

선택 매개변수

ALLOW_WRITES = '{ TRUE | FALSE }': 외부 볼륨에 쓰기 작업을 허용할지 지정해요. 다음 테이블에 대해 TRUE로 설정해야 해요:
- Snowflake를 카탈로그로 사용하는 Iceberg 테이블.
- 외부 카탈로그를 사용하고 쓰기 가능한 Iceberg 테이블. 외부 관리 Iceberg 테이블은 ALLOWED_WRITE_OPERATIONS 매개변수가 TRUE로 설정된 카탈로그 연결(catalog-linked) 데이터베이스를 통해 접근할 때 쓰기 가능해요.
- Delta 테이블 파일에서 만든 Iceberg 테이블에 대해 TRUE로 설정하면 Snowflake가 Iceberg 메타데이터를 외부 저장소에 쓸 수 있어요.
기본값: TRUE. 읽기 전용으로만 외부 관리 Iceberg 테이블을 읽을 계획이라면 FALSE로 설정할 수 있어요.
COMMENT = 'string_literal': 외부 볼륨에 대한 주석 문자열을 지정해요. 기본값: 값 없음.

클라우드 공급자 매개변수 (cloudProviderParams)

KMS 키는 Amazon S3 또는 Google Cloud Storage 인스턴스에서 저장소 소유자가 관리해요. 서비스 주체(IAM 역할, GCS 서비스 계정)에 KMS 키 사용 권한을 부여해야 해요.

Amazon S3

STORAGE_PROVIDER = '{ S3 | S3GOV }': 데이터 파일을 저장하는 클라우드 저장소 공급자를 지정해요. 'S3'는 중국 외 공개 AWS 리전, 'S3GOV'는 AWS 정부 리전을 의미해요.
STORAGE_AWS_ROLE_ARN = 'iam_role': 데이터 파일이 있는 S3 버킷에 권한을 부여하는 AWS IAM 역할의 대/소문자 구분 Amazon Resource Name(ARN)을 지정해요.
STORAGE_BASE_URL = 'protocol://bucket[/path/]': 클라우드 저장소 위치의 기본 URL을 지정해요. protocol은 s3(중국 외 공개 리전) 또는 s3gov(정부 리전)이고, bucket은 데이터 파일을 저장하는 S3 버킷 이름 또는 S3 버킷 액세스 포인트의 버킷 스타일 별칭, path는 버킷 내 객체에 대한 세분화된 제어를 위한 선택적 경로예요.
- Snowflake는 점(.)이 포함된 S3 버킷 이름(예: my.s3.bucket)을 가진 외부 볼륨을 지원하지 않아요.
- 외부 카탈로그를 사용하는 Iceberg 테이블을 만들려면 Parquet 데이터 파일과 Iceberg 메타데이터 파일이 STORAGE_BASE_URL 위치 내에 있어야 해요.
STORAGE_AWS_ACCESS_POINT_ARN = 'string': S3 액세스 포인트의 ARN을 지정해요. 저장소 STORAGE_BASE_URL에 S3 액세스 포인트 별칭을 지정할 때만 필요해요.
STORAGE_AWS_EXTERNAL_ID = 'external_id': Snowflake가 AWS와 신뢰 관계를 구축하는 데 사용하는 외부 ID를 선택적으로 지정해요. 이 외부 볼륨에 대해 구성한 IAM 역할의 신뢰 정책에 동일한 외부 ID를 지정해야 해요. 지정하지 않으면 Snowflake가 외부 볼륨 생성 시 자동으로 생성해요.
ENCRYPTION = ( [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = 'string' ] ] | [ TYPE = 'NONE' ] ): 외부 볼륨의 데이터 암호화 속성을 지정해요.
- 'AWS_SSE_S3': S3 관리 암호화 키를 사용하는 서버 측 암호화.
- 'AWS_SSE_KMS': KMS에 저장된 키를 사용하는 서버 측 암호화.
- 'NONE': 암호화 없음.
- KMS_KEY_ID = 'string' (AWS_SSE_KMS에만 해당): 버킷에 쓰는 파일을 암호화하는 AWS KMS 관리 키의 ID를 선택적으로 지정해요. 값을 제공하지 않으면 기본 KMS 키가 사용돼요. 읽을 때는 이 값이 무시돼요.
  - Snowflake Horizon Catalog 자격 증명 제공(credential vending)과 함께 이 외부 볼륨을 사용하려면 KMS_KEY_ID를 전체 키 ARN으로 설정하거나, Snowflake가 ARN을 해석할 수 있도록 외부 볼륨의 IAM 역할에 kms:DescribeKey 권한을 부여하세요. KMS 키 별칭은 자격 증명 제공에 지원되지 않아요.
USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }: 보안 자세를 강화하기 위해 아웃바운드 프라이빗 연결을 사용할지 지정해요.

Google Cloud Storage

STORAGE_PROVIDER = 'GCS': 데이터 파일을 저장하는 클라우드 저장소 공급자를 지정해요.
STORAGE_BASE_URL = 'gcs://bucket[/path/]': 클라우드 저장소 위치의 기본 URL을 지정해요. bucket은 데이터 파일을 저장하는 Cloud Storage 버킷 이름, path는 선택적 경로예요.
ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = 'string' ] | [ TYPE = 'NONE' ] ): 암호화 속성을 지정해요.
- 'GCS_SSE_KMS': KMS에 저장된 키를 사용하는 서버 측 암호화.
- 'NONE': 암호화 없음.
- KMS_KEY_ID = 'string' (GCS_SSE_KMS에만 해당): 버킷에 쓰는 파일을 암호화하는 Cloud KMS 관리 키의 ID를 지정해요. 읽을 때는 무시돼요.

Microsoft Azure

STORAGE_PROVIDER = 'AZURE': 데이터 파일을 저장하는 클라우드 저장소 공급자를 지정해요.
AZURE_TENANT_ID = 'tenant_id': 저장소 위치가 속한 Office 365 테넌트의 ID를 지정해요. 외부 볼륨은 하나의 테넌트에만 인증할 수 있어요. Azure 포털에서 Azure Active Directory » Properties를 선택해 테넌트 ID를 찾을 수 있어요.
STORAGE_BASE_URL = 'azure://...': 클라우드 저장소 위치의 기본 URL(대/소문자 구분)을 지정해요.
- Azure Blob Storage: azure://account.blob.core.windows.net/container[/path/]
- Data Lake Storage: azure://account.dfs.core.windows.net/container[/path/]
- Fabric OneLake: azure://[region-]onelake.{dfs | blob}.fabric.microsoft.com/workspace/lakehouse/path/
- azure:// 접두사를 사용하고 https://는 사용하지 마세요.
USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }: 보안 자세를 강화하기 위해 아웃바운드 프라이빗 연결을 사용할지 지정해요.

S3 호환 저장소 매개변수 (s3CompatibleStorageParams)

STORAGE_PROVIDER = 'S3COMPAT': 저장소 공급자로 S3 호환 저장소를 지정해요.
STORAGE_BASE_URL = 's3compat://bucket[/path/]': 데이터 파일을 저장하는 외부 위치의 URL을 지정해요. bucket은 버킷 이름, path는 선택적 대/소문자 구분 경로(또는 S3 용어로 접두사)예요.
CREDENTIALS = ( AWS_KEY_ID = 'string' AWS_SECRET_KEY = 'string' ): S3 호환 저장소 위치에 연결하고 접근하기 위한 보안 자격 증명을 지정해요.
STORAGE_ENDPOINT = 's3_api_compatible_endpoint': S3 호환 API 엔드포인트를 가리키는 정규화된 도메인을 지정해요. 엔드포인트에는 버킷 이름을 포함하지 마세요 (예: my_bucket.example.com 대신 example.com).

접근 제어 요구 사항

이 작업을 실행하려면 역할에 최소한 다음 권한이 필요해요:

권한	객체	참고
CREATE EXTERNAL VOLUME	계정	기본적으로 ACCOUNTADMIN 역할만 이 권한을 가져요. 필요에 따라 추가 역할에 부여할 수 있어요.

사용법 참고 사항

Amazon S3 저장소 전용: 외부 ID를 지정하지 않고 CREATE OR REPLACE EXTERNAL VOLUME 구문으로 외부 볼륨을 다시 만들면, Snowflake 계정의 AWS IAM 사용자에게 S3 저장소 위치에 필요한 접근 권한을 부여하는 단계를 반복해야 해요.
하나 이상의 Iceberg 테이블이 외부 볼륨과 연관되어 있으면 외부 볼륨을 드롭하거나 교체할 수 없어요.
외부 볼륨에 의존하는 테이블을 보려면 SHOW ICEBERG TABLES 명령과 파이프 연산자(->>)를 사용해 external_volume_name 컬럼을 필터링하는 쿼리를 사용할 수 있어요. 컬럼 식별자(external_volume_name)는 대/소문자를 구분하므로 SHOW 출력에 나타난 그대로 지정하세요.

SHOW ICEBERG TABLES
  ->> SELECT *
        FROM $1
        WHERE "external_volume_name" = 'my_external_volume_1';

Microsoft Fabric OneLake 저장소 위치에 리전 엔드포인트를 사용하면 Microsoft Fabric 용량과 같은 리전을 사용하세요. 이 역시 Snowflake 계정을 호스팅하는 리전과 같아야 해요.
S3 액세스 포인트를 사용하는 S3 외부 볼륨의 경우 외부 볼륨의 IAM 정책이 S3 액세스 포인트에 대한 권한을 부여하도록 구성해야 해요. 멀티 리전 액세스 포인트는 지원되지 않아요.
OR REPLACE와 IF NOT EXISTS 절은 상호 배타적이에요.
CREATE OR REPLACE <object> 문은 원자적이에요.

예제 (Examples)

다음 예들은 다양한 클라우드 공급자로 쓰기 가능한 저장소 위치를 정의하는 외부 볼륨을 만들어요.

Amazon S3: 암호화가 있는 S3 저장소 위치를 정의하는 외부 볼륨을 만들어요.

CREATE OR REPLACE EXTERNAL VOLUME exvol
  STORAGE_LOCATIONS =
      (
        (
            NAME = 'my-s3-us-west-2'
            STORAGE_PROVIDER = 'S3'
            STORAGE_BASE_URL = 's3://my-example-bucket/'
            STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/myrole'
            ENCRYPTION = ( TYPE = 'AWS_SSE_KMS' KMS_KEY_ID = '1234abcd-12ab-34cd-56ef-1234567890ab' )
        )
      )
  ALLOW_WRITES = TRUE;

Google Cloud Storage: 암호화가 있는 GCS 저장소 위치를 정의하는 외부 볼륨을 만들어요.

CREATE EXTERNAL VOLUME exvol
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'my-us-east-1'
        STORAGE_PROVIDER = 'GCS'
        STORAGE_BASE_URL = 'gcs://mybucket1/path1/'
        ENCRYPTION=(TYPE='GCS_SSE_KMS' KMS_KEY_ID = '1234abcd-12ab-34cd-56ef-1234567890ab')
      )
    )
  ALLOW_WRITES = TRUE;

Microsoft Azure: 암호화가 있는 Azure 저장소 위치를 정의하는 외부 볼륨을 만들어요.

CREATE EXTERNAL VOLUME exvol
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'my-azure-northeurope'
        STORAGE_PROVIDER = 'AZURE'
        STORAGE_BASE_URL = 'azure://exampleacct.blob.core.windows.net/my_container_northeurope/'
        AZURE_TENANT_ID = 'a123b4c5-1234-123a-a12b-1a23b45678c9'
      )
    )
  ALLOW_WRITES = TRUE;

S3 호환 저장소: S3 호환 저장소 위치를 정의하는 외부 볼륨을 만들어요.

CREATE OR REPLACE EXTERNAL VOLUME ext_vol_s3_compat
  STORAGE_LOCATIONS = (
    (
      NAME = 'my_s3_compat_storage_location'
      STORAGE_PROVIDER = 'S3COMPAT'
      STORAGE_BASE_URL = 's3compat://mybucket/unload/mys3compatdata'
      CREDENTIALS = (
        AWS_KEY_ID = '1a2b3c...'
        AWS_SECRET_KEY = '4x5y6z...'
      )
      STORAGE_ENDPOINT = 'example.com'
    )
  );

더 알아보기 (Learn more)

ALTER EXTERNAL VOLUME
DROP EXTERNAL VOLUME
SHOW EXTERNAL VOLUMES
DESCRIBE EXTERNAL VOLUME
외부 볼륨 구성, Apache Iceberg™ 테이블의 메타데이터와 보존