CREATE EXTERNAL VOLUME

アカウントの Apache Iceberg™ テーブル 用に新しい 外部ボリューム を作成するか、既存の外部ボリュームを置き換えます。

こちらもご参照ください。

ALTER EXTERNAL VOLUME、 DROP EXTERNAL VOLUME、 SHOW EXTERNAL VOLUMES、 DESCRIBE EXTERNAL VOLUME

構文

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に設定された、カタログにリンクされたデータベースを通じてアクセスすると書き込み可能です。

デルタテーブルファイルから作成されたIcebergテーブルの場合、このパラメーターを TRUE に設定すると、Snowflakeが外部ストレージにIcebergメタデータを書き込みます。詳細については、 Deltaベーステーブル をご参照ください。

The value of this parameter must also match the permissions that you set on the cloud storage account for each specified storage location. For Delta Direct (Iceberg tables created from Delta table files in object storage), including read-only configuration with ALLOW_WRITES = FALSE (for example the Storage Blob Data Reader role on Microsoft Azure, or IAM on Amazon S3 and Google Cloud Storage without object write actions), see Read-only vs write access for Delta Direct on each storage provider in Apache Iceberg™ テーブルのメタデータと保持. That section links to the step-by-step external volume topics for each provider. For the general action lists Snowflake expects by cloud provider and table type, see Granting Snowflake access to your storage. For step-by-step IAM setup (for example policies and roles for Amazon S3, Google Cloud Storage, or Microsoft Azure), see 外部ボリュームの構成.

注釈

If you plan to use the external volume for only reading externally managed Iceberg tables, you can set this parameter to FALSE and Snowflake will not write data or Iceberg metadata files to your cloud storage when you refresh tables.

デフォルト: TRUE

COMMENT = 'string_literal'

外部ボリュームのコメントを指定する文字列（リテラル）。

デフォルト: 値なし

クラウドプロバイダーのパラメーター（cloudProviderParams）

注釈

KMS キーは、Amazon S3またはGoogle Cloud Storageインスタンスのストレージ所有者によって管理されます。サービスプリンシパル（IAM ロールと GCS サービスアカウント）に、KMS キーを使用する権限を付与する必要があります。詳細については、 テーブルファイルの暗号化 をご参照ください。

Amazon S3

STORAGE_PROVIDER = '{ S3 | S3GOV }'

データファイルを保存するクラウドストレージプロバイダーを指定します。

  • 'S3': 中国国外のパブリック AWS リージョンにある S3 ストレージ。

  • 'S3GOV': プレフィックスは、 AWS 政府リージョン のS3ストレージを参照します。

STORAGE_AWS_ROLE_ARN = 'iam_role'

データファイルを含むS3バケットに対する権限を付与する AWS IDおよびアクセス管理（IAM）ロールの大文字と小文字を区別するAmazonリソースネーム（ARN）を指定します。詳細については、 Amazon S3用の外部ボリュームを構成する をご参照ください。

STORAGE_BASE_URL = 'protocol://bucket[/path/]'

クラウドストレージの場所のベース URL を指定します。

  • protocol は以下のいずれかです。

    • s3 プレフィックスは、中国以外のパブリック AWS リージョンのS3ストレージを参照します。

    • s3gov プレフィックスは、 政府リージョン のS3ストレージを参照します。

  • bucket は、データファイルを保存するS3バケットの名前、またはS3バケットアクセスポイントの バケットスタイルのエイリアス です。S3アクセスポイントの場合は、 STORAGE_AWS_ACCESS_POINT_ARN パラメーターの値も指定する必要があります。

  • path は、バケット内のオブジェクトを細かく制御するために使用できるオプションのパスです。

注釈

Snowflakeは、ドットを含むS3バケット名を持つ外部ボリュームをサポートできません（例えば、 my.s3.bucket）。S3は、名前にドットが含まれる仮想ホスト形式のバケットの SSL をサポートしておらず、Snowflakeは仮想ホスト形式のパスと HTTPS を使用してS3のデータにアクセスします。

重要

外部カタログを使用するIcebergテーブルを作成するには、ParquetデータファイルとIcebergメタデータファイルが STORAGE_BASE_URL の場所にある必要があります。

STORAGE_AWS_ACCESS_POINT_ARN = 'string'

S3アクセスポイントのAmazonリソース名（ARN）を指定します。ストレージ STORAGE_BASE_URL にS3アクセスポイントエイリアスを指定する場合にのみ必要です。

STORAGE_AWS_EXTERNAL_ID = 'external_id'

オプションで、Snowflakeが AWS との信頼関係を確立するために使用する外部 ID を指定します。この外部ボリュームに設定した IAM ロールの信頼ポリシーで、同じ外部 ID を指定する必要があります。詳細については、 サードパーティに AWS リソースへのアクセスを許可する場合の外部 ID の使用方法 をご参照ください。

このパラメーターに値を指定しない場合、Snowflakeは外部ボリュームの作成時に自動的に外部 ID を生成します。

ENCRYPTION = ( [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = 'string' ] ] | [ TYPE = 'NONE' ] )

外部ボリューム上のデータを暗号化するために必要なプロパティを指定します。

TYPE = ...

使用される暗号化タイプを指定します。可能な値は次のとおりです。

KMS_KEY_ID = 'string' （AWS_SSE_KMS 暗号化のみに適用）

オプションで、バケットに 書き込まれた ファイルの暗号化に使用する AWS KMS が管理するキーの ID を指定します。値が指定されていない場合、デフォルトの KMS キーを使用して、データの書き込み時にファイルが暗号化されます。

この値はデータの読み込み時には無視されことに注意してください。

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

セキュリティ体制を強化するためにアウトバウンドプライベート接続を使用するかどうかを指定します。このパラメーターの使用に関する情報については、 Amazon Web Services の外部ボリュームへのプライベート接続 をご参照ください。

Google Cloud Storage

STORAGE_PROVIDER = 'GCS'

データファイルを保存するクラウドストレージプロバイダーを指定します。

STORAGE_BASE_URL = 'gcs://bucket[/path/]'

クラウドストレージの場所のベース URL を指定します。

  • bucket は、データファイルを保存するCloud Storageバケットの名前です。

  • path は、バケット内のオブジェクトを細かく制御するために使用できるオプションのパスです。

重要

外部カタログを使用するIcebergテーブルを作成するには、ParquetデータファイルとIcebergメタデータファイルが STORAGE_BASE_URL の場所にある必要があります。

ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = 'string' ] | [ TYPE = 'NONE' ] )

外部ボリューム上のデータを暗号化するために必要なプロパティを指定します。

TYPE = ...

使用される暗号化タイプを指定します。可能な値は次のとおりです。

  • 'GCS_SSE_KMS': KMS に格納されたキーを使用したサーバー側の暗号化。詳細については、 顧客管理暗号化キー をご覧ください。

  • 'NONE' ：暗号化なし。

KMS_KEY_ID = 'string' （GCS_SSE_KMS 暗号化のみに適用）

バケットに 書き込まれた ファイルの暗号化に使用するCloud KMS 管理キーの ID を指定します。

この値はデータの読み込み時には無視されことに注意してください。サービスアカウントにデータと指定された KMS キーに対して十分な権限がある場合、読み取り操作は成功するはずです。

Microsoft Azure

STORAGE_PROVIDER = 'AZURE'

データファイルを保存するクラウドストレージプロバイダーを指定します。

AZURE_TENANT_ID = 'tenant_id'

ストレージの場所が属する Office 365 テナントの ID を指定します。外部ボリュームは1つのテナントのみを認証できるため、許可およびブロックされたストレージの場所は、このテナントに属するすべてストレージアカウントを参照する必要があります。

テナント ID を見つけるには、Azureポータルにログインして Azure Active Directory » Properties を選択します。テナント ID が Tenant ID フィールドに表示されます。

STORAGE_BASE_URL = 'azure://...'

クラウドストレージの場所のベース URL を指定します（大文字と小文字を区別）。

  • Azure Blob Storageの場合は、 azure://account.blob.core.windows.net/container[/path/] を指定します。この場合、

    • account はAzureアカウント名で、例えば myaccount です。

    • container は、データファイルを保存するAzureコンテナーの名前です。

    • path は、コンテナー内の論理ディレクトリを細かく制御するために使用できるオプションのパスです。

Snowflakeのロゴ（黒）（文字なし） プレビュー機能 --- オープン

すべてのアカウントで利用可能です。データレイクストレージに接続された外部ボリュームの構成機能は、現在パブリックプレビューです。

  • データレイクストレージの場合は、:samp:`azure://{account}.dfs.core.windows.net/{container}[/{path}/]`を指定します。ここで：

    • account はAzureアカウント名で、例えば myaccount です。

    • container は、データファイルを保存するAzureコンテナーの名前です。

    • path は、コンテナー内の論理ディレクトリを細かく制御するために使用できるオプションのパスです。

  • Fabric OneLake の場合は、 azure://[region-]onelake.dfs | blob.fabric.microsoft.com/workspace/lakehouse/path/ を指定します。

    • region は、オプションでエンドポイントリージョンを指定します。例: westus。指定する場合は、Microsoft Fabric容量が使用するリージョンと、Snowflakeアカウントがホストされているリージョンを同じにする必要があります。

    • dfs | blob は、エンドポイントのタイプを指定します。

    • workspace は、Fabricワークスペース ID またはワークスペース名です。例: cfafbeb1-8037-4d0c-896e-a46fb27ff227 または my_workspace。ワークスペースとレイクハウスの両方で、同じタイプの識別子（ID または名前）を使用する必要があります。

    • lakehouse は、レイクハウス ID またはレイクハウス名です。ワークスペースとレイクハウスの両方で、同じタイプの識別子（ID または名前）を使用する必要があります。例: 5b218778-e7a5-4d73-8187-f10824047715 または my_lakehouse.Lakehouse。

    • path は、指定したレイクハウスとワークスペースにあるストレージの場所へのパスです。

    Snowflakeのロゴ（黒）（文字なし） プレビュー機能 --- オープン

    すべてのアカウントで利用可能です

    この機能は中華人民共和国ではご利用いただけません。

注釈

プレフィックスには、 https:// ではなく azure:// を使用します。

重要

外部カタログを使用するIcebergテーブルを作成するには、ParquetデータファイルとIcebergメタデータファイルが STORAGE_BASE_URL の場所にある必要があります。

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

セキュリティ体制を強化するためにアウトバウンドプライベート接続を使用するかどうかを指定します。このパラメーターの使用に関する情報については、 Microsoft Azure の外部ボリュームへのプライベート接続 をご参照ください。

S3互換ストレージパラメーター（s3CompatibleStorageParams）

STORAGE_PROVIDER = 'S3COMPAT'

ストレージプロバイダーとしてS3互換ストレージを指定します。

STORAGE_BASE_URL = 's3compat://bucket[/path/]'

データファイルの保存に使用する外部ロケーション（S3互換の API エンドポイントを使用してアクセスする既存のバケット）の 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

アカウント

Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

指定された権限のセットを使用してカスタムロールを作成する手順については、 カスタムロールの作成 をご参照ください。

セキュリティ保護可能なオブジェクト に対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、 アクセス制御の概要 をご参照ください。

使用上の注意

重要

Amazon S3ストレージの外部ボリュームのみ: 外部 ID を指定せずに外部ボリュームを再作成する場合（CREATE OR REPLACE EXTERNAL VOLUME 構文を使用）は、Snowflakeアカウントの AWS IDおよびアクセス管理（IAM）ユーザーに、S3ストレージの場所に必要なアクセス許可を付与するステップを繰り返す必要があります。詳細については、 Amazon S3用の外部ボリュームを構成する のSnowflakeアカウントの AWS IAM ユーザーを検索する手順をご参照ください。

  • 1つまたは複数のIcebergテーブルが外部ボリュームに関連付けられている場合は、外部ボリュームをドロップまたは交換することができません。

    外部ボリュームに依存するテーブルを表示するには、SHOW ICEBERG TABLES コマンドと、external_volume_name 列でフィルターする :doc:` パイプ演算子 </sql-reference/operators-flow>`（->>）を使用したクエリを使用できます。

    注釈

    列識別子（external_volume_name）は大文字と小文字を区別します。SHOW ICEBERG TABLES 出力に表示されるのと同じように、列識別子を指定します。

    例:

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

  • Microsoft Fabric OneLake のストレージロケーションにリージョンのエンドポイントを使用する場合は、Microsoft Fabricの容量と同じリージョンを使用します。これは、Snowflakeアカウントをホストしているリージョンとも同じにする必要があります。

  • S3アクセスポイントを使用するS3外部ボリュームの場合、

  • メタデータについて:

    注意

    Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。

  • OR REPLACE 句と IF NOT EXISTS 句は互いに排他的です。この2つを同じステートメントで使うことはできません。

  • CREATE OR REPLACE <オブジェクト> ステートメントはアトミックです。つまり、オブジェクトが置き換えられると、単一のトランザクションで、古いオブジェクトが削除されて新しいオブジェクトが作成されます。

例

以下の例では、異なるクラウドプロバイダーで書き込み可能なストレージロケーションを定義する外部ボリュームを作成します。

Amazon S3

次の例は、暗号化されたAmazon 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互換のストレージ場所を定義する外部ボリュームを作成します。詳細については、 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'
    )
  );