CREATE EXTERNAL VOLUME

Crée un nouveau volume externe pour Tables Iceberg dans le compte ou remplace un volume externe existant.

Voir aussi :

ALTER EXTERNAL VOLUME , DROP EXTERNAL VOLUME , SHOW EXTERNAL VOLUMES, DESCRIBE EXTERNAL VOLUME

Dans ce chapitre :

Syntaxe

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

Où :

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  STORAGE_BASE_URL = 's3://<bucket>[/<path>/]'
  [ STORAGE_AWS_EXTERNAL_ID = '<external_id>' ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_SSE_S3' ] |
              [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] |
              [ TYPE = 'NONE' ] ) ]
Copy
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' ] ) ]
Copy
cloudProviderParams (for Microsoft Azure) ::=
  STORAGE_PROVIDER = 'AZURE'
  AZURE_TENANT_ID = '<tenant_id>'
  STORAGE_BASE_URL = 'azure://<account>.blob.core.windows.net/<container>[/<path>/]'
Copy

Paramètres requis

storage_location_name

Chaîne spécifiant l’identificateur (le nom) du volume externe ; doit être unique sur votre compte.

L’identificateur doit commencer par un caractère alphabétique et ne peut pas contenir d’espaces ni de caractères spéciaux, sauf si toute la chaîne d’identificateur est placée entre des guillemets doubles (par exemple, "My object"). Les identificateurs entre guillemets doubles sont également sensibles à la casse.

Pour plus de détails, voir Exigences relatives à l’identificateur.

STORAGE_LOCATIONS = ( ( NAME = 'name' cloudProviderParams ) [, (...), ...] )

Ensemble d’emplacements de stockage Cloud nommés dans différentes régions et, éventuellement, de plateformes Cloud.

Note

  • Pendant la période d’avant-première, chaque volume externe que vous créez prend en charge un seul emplacement de stockage actif.

  • Les tables inter-Cloud et interrégionales ne sont pas actuellement prises en charge lorsque vous utilisez Snowflake comme catalogue Iceberg.

Paramètres facultatifs

ALLOW_WRITES = '{ TRUE | FALSE }'

Spécifie si les opérations d’écriture sont autorisées pour le volume externe ; doit être défini sur TRUE pour les tables Iceberg qui utilisent Snowflake comme catalogue.

La valeur de ce paramètre doit également correspondre aux autorisations définies sur le compte de stockage Cloud pour chaque emplacement de stockage spécifié.

Par défaut : TRUE

COMMENT = 'string_literal'

Chaîne (littéral) qui spécifie un commentaire pour le volume externe.

Par défaut : aucune valeur

Paramètres du fournisseur Cloud (cloudProviderParams)

Note

Les clés KMS sont gérées par le propriétaire du stockage dans des instances Amazon S3 ou Google Cloud Storage. Les principaux de service (rôle IAM et compte de service GCS) doivent se voir accorder des privilèges permettant d’utiliser des clés KMS. Pour plus d’informations, voir Configurer un volume externe pour des tables Iceberg.

Amazon S3

STORAGE_PROVIDER = 'S3'

Spécifie le fournisseur de stockage dans le Cloud qui stocke vos fichiers de données.

STORAGE_AWS_ROLE_ARN = 'iam_role'

Spécifie le nom de ressource Amazon (ARN) du rôle AWS de gestion des identités et des accès (IAM) qui octroie des privilèges sur le compartiment S3 contenant vos fichiers de données. Pour plus d’informations, voir Configuration de l’accès sécurisé à Amazon S3.

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

Spécifie l’URL de base de votre emplacement de stockage Cloud, où :

  • bucket est le nom d’un compartiment S3 qui stocke vos fichiers de données.

  • path est un chemin facultatif qui peut être utilisé pour fournir un contrôle granulaire sur les objets du compartiment.

Important

Pour créer une table Iceberg qui utilise un catalogue externe, vos fichiers de données Parquet et vos fichiers de métadonnées Iceberg doivent se trouver dans l’emplacement STORAGE_BASE_URL.

STORAGE_AWS_EXTERNAL_ID = 'external_id'

Spécifie optionnellement un ID externe que Snowflake utilise pour établir une relation de confiance avec AWS. Vous devez spécifier le même ID externe dans la politique de confiance du rôle IAM que vous avez configuré pour ce volume externe. Pour plus d’informations, voir Comment utiliser un ID externe lorsque vous accordez l’accès à vos ressources AWS à un tiers.

Si vous ne spécifiez pas de valeur pour ce paramètre, Snowflake génère automatiquement un ID externe lorsque vous créez le volume externe.

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

Spécifie les propriétés nécessaires au chiffrement des données sur le volume externe.

TYPE = ...

Indique le type de chiffrement utilisé. Les valeurs possibles sont les suivantes :

KMS_KEY_ID = 'string' (s’applique uniquement au chiffrement AWS_SSE_KMS)

Spécifie éventuellement l’ID de la clé gérée par AWS KMS qui est utilisée pour chiffrer les fichiers écrits dans le compartiment. Si aucune valeur n’est fournie, votre clé KMS par défaut est utilisée pour chiffrer les fichiers pour écrire les données.

Notez que cette valeur est ignorée lors de la lecture des données.

Google Cloud Storage

STORAGE_PROVIDER = 'GCS'

Spécifie le fournisseur de stockage dans le Cloud qui stocke vos fichiers de données.

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

Spécifie l’URL de base de votre emplacement de stockage Cloud, où :

  • bucket est le nom d’un compartiment Cloud Storage qui stocke vos fichiers de données.

  • path est un chemin facultatif qui peut être utilisé pour fournir un contrôle granulaire sur les objets du compartiment.

Important

Pour créer une table Iceberg qui utilise un catalogue externe, vos fichiers de données Parquet et vos fichiers de métadonnées Iceberg doivent se trouver dans l’emplacement STORAGE_BASE_URL.

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

Spécifie les propriétés nécessaires au chiffrement des données sur le volume externe.

TYPE = ...

Indique le type de chiffrement utilisé. Les valeurs possibles sont les suivantes :

KMS_KEY_ID = 'string' (s’applique uniquement au chiffrement GCS_SSE_KMS)

Spécifie l’ID de la clé gérée par Cloud KMS qui est utilisée pour chiffrer les fichiers écrits dans le compartiment.

Notez que cette valeur est ignorée lors de la lecture des données. L’opération de lecture devrait réussir si le compte de service dispose d’autorisations suffisantes pour les données et des clés KMS spécifiées.

Microsoft Azure

STORAGE_PROVIDER = 'AZURE'

Spécifie le fournisseur de stockage dans le Cloud qui stocke vos fichiers de données.

AZURE_TENANT_ID = 'tenant_id'

Spécifie l” ID de votre client Office 365 auquel appartiennent les comptes de stockage autorisés et bloqués. Un volume externe peut s’authentifier auprès d’un seul client, de sorte que les emplacements de stockage autorisés et bloqués doivent donc faire référence aux comptes de stockage qui appartiennent tous à ce client.

Pour trouver votre ID de client, connectez-vous au portail Azure et cliquez sur Azure Active Directory » Properties. L” ID de client s’affiche dans le champ Tenant ID.

STORAGE_BASE_URL = 'azure://account.blob.core.windows.net/container[/path/]'

Spécifie l’URL de base de votre emplacement de stockage Cloud, où :

  • account est le nom de votre compte Azure ; par exemple, myaccount.

  • container est le nom d’un conteneur Azure qui stocke vos fichiers de données.

  • path est un chemin facultatif qui peut être utilisé pour fournir un contrôle granulaire sur les répertoires logiques du conteneur.

Note

Utilisez le préfixe azure:// et non https://.

Important

Pour créer une table Iceberg qui utilise un catalogue externe, vos fichiers de données Parquet et vos fichiers de métadonnées Iceberg doivent se trouver dans l’emplacement STORAGE_BASE_URL.

Exigences en matière de contrôle d’accès

Un rôle utilisé pour exécuter cette commande SQL doit avoir les privilèges suivants définis au minimum ainsi :

Privilège

Objet

Remarques

CREATE EXTERNAL VOLUME

Compte

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

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation

Important

Volumes externes dans le stockage Amazon S3 uniquement : Si vous recréez un volume externe (via la syntaxe CREATE OR REPLACE EXTERNAL VOLUME), vous devez répéter les étapes permettant d’accorder à l’utilisateur IAM (Identity and Access Management - Gestion de l’identité et de l’accès) AWS de votre compte Snowflake les autorisations d’accès requises sur l’emplacement de stockage S3. Pour des instructions, voir les étapes commençant par Étape 5 : Récupérer l’utilisateur IAM AWS de votre compte Snowflake.

  • Concernant les métadonnées :

    Attention

    Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

  • Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

Exemples

Les exemples suivants créent des volumes externes qui définissent des emplacements de stockage auprès de différents fournisseurs Cloud :

Amazon S3

L’exemple suivant crée un volume externe qui définit un emplacement de stockage Amazon S3 avec chiffrement :

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')
        )
      );
Copy

Google Cloud Storage

L’exemple suivant crée un volume externe qui définit un emplacement de stockage GCS avec chiffrement :

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')
      )
    );
Copy

Microsoft Azure

L’exemple suivant crée un volume externe qui définit un emplacement de stockage Azure avec chiffrement :

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'
      )
    );
Copy