CREATE EXTERNAL VOLUME¶

Syntaxe¶

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

Où :

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 } ]

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://...'
  [ USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } ]

Copy

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>'

Copy

Paramètres requis¶

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 = 'storage_location_name' { cloudProviderParams | s3CompatibleStorageParams } ) [, (...), ...] )

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

Note

• 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é.

Note

Si vous prévoyez d’utiliser le volume externe pour des tables Iceberg gérées en externe, vous pouvez définir ce paramètre sur FALSE. Snowflake n’écrit pas de fichiers de métadonnées Iceberg ni de données dans votre stockage Cloud lorsque vous utilisez un catalogue Iceberg externe.

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)¶

Amazon S3

STORAGE_PROVIDER = '{ S3 | S3GOV }'

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

• 'S3' : stockage S3 dans des régions AWS publiques hors Chine.

• 'S3GOV' : stockage S3 dans les régions gouvernementales AWS.

STORAGE_AWS_ROLE_ARN = 'iam_role'

Spécifie le nom de ressource Amazon (Amazon Resource Name ou ARN) sensible à la casse du rôle de gestion des identités et des accès (Identity and Access Management ou IAM) AWS qui octroie des privilèges sur le compartiment S3 contenant vos fichiers de données. Pour plus d’informations, voir Configurer un volume externe pour Amazon S3.

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

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

• protocol est l’un des éléments suivants :

  • s3 fait référence au stockage S3 dans les régions AWS publiques hors de Chine.

  • s3gov fait référence au stockage S3 dans les régions gouvernementales.

• bucket est le nom d’un compartiment S3 qui stocke vos fichiers de données ou l”alias de type compartiment pour un point d’accès au compartiment S3. Pour un point d’accès S3, vous devez également spécifier une valeur pour le paramètre STORAGE_AWS_ACCESS_POINT_ARN.

• 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_ACCESS_POINT_ARN = 'string'

Spécifie le nom de la ressource Amazon (ARN) pour votre point d’accès S3. Obligatoire uniquement lorsque vous spécifiez un alias de point d’accès S3 pour votre stockage 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 :

• 'AWS_SSE_S3' : Chiffrement côté serveur à l’aide de clés de chiffrement gérées par S3. Pour plus d’informations, voir Utilisation du chiffrement côté serveur à l’aide de clés de chiffrement gérées par Amazon S3 (SSE-S3).

• 'AWS_SSE_KMS' : Chiffrement côté serveur à l’aide de clés stockées dans KMS. Pour plus d’informations, voir Utilisation du chiffrement côté serveur à l’aide du service de gestion de clés AWS (SSE-KMS).

• 'NONE' : pas de chiffrement.

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.

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

Indique s’il faut utiliser la connectivité privée sortante pour renforcer votre sécurité. Pour obtenir des informations sur l’utilisation de ce paramètre, voir Connectivité privée vers des volumes externes pour AWS.

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 :

• 'GCS_SSE_KMS' : Chiffrement côté serveur à l’aide de clés stockées dans KMS. Pour plus d’informations, voir clés de chiffrement gérées par le client.

• 'NONE' : pas de chiffrement.

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 appartient l’emplacement de stockage. Un volume externe peut s’authentifier auprès d’un seul client, de sorte que l’emplacement de stockage doit faire référence à un compte de stockage qui appartient à ce client.

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

STORAGE_BASE_URL = 'azure://...'

Spécifie l’URL de base de votre emplacement de stockage Cloud (sensible à la casse).

• Pour le stockage Azure Blob, indiquez azure://account.blob.core.windows.net/container[/path/], 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.

• For Fabric OneLake, spécifiez azure://[region-]onelake.dfs | blob.fabric.microsoft.com/workspace/lakehouse/Files/path/, où :

  • region spécifie éventuellement la région du point de terminaison ; par exemple, westus. Si spécifiée, il doit s’agir de la même région que celle utilisée par votre capacité Microsoft Fabric, et de la même région que celle dans laquelle votre compte Snowflake est hébergé.

  • dfs | blob spécifie le type de point de terminaison.

  • workspace est soit l’ID de votre espace de travail Fabric soit le nom de votre espace de travail ; par exemple, cfafbeb1-8037-4d0c-896e-a46fb27ff227 ou my_workspace. Vous devez utiliser le même type d’identificateur (ID ou nom) pour votre espace de travail et pour Lakehouse.

  • lakehouse est soit l’ID de votre Lakehouse, soit le nom de votre Lakehouse. Vous devez utiliser le même type d’identificateur (ID ou nom) pour votre espace de travail et pour Lakehouse ; par exemple, 5b218778-e7a5-4d73-8187-f10824047715 ou my_lakehouse.Lakehouse.

  • path est un chemin vers votre emplacement de stockage dans Lakehouse et l’espace de travail spécifiés.

  Fonctionnalité en avant-première — En accès libre

  Disponible pour tous les comptes.

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.

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

Indique s’il faut utiliser la connectivité privée sortante pour renforcer votre sécurité. Pour obtenir des informations sur l’utilisation de ce paramètre, voir Connectivité privée vers des volumes externes pour Microsoft Azure.

Paramètres de stockage compatibles S3 (s3CompatibleStorageParams)¶

STORAGE_PROVIDER = 'S3COMPAT'

Spécifie le stockage compatible S3 comme votre fournisseur de stockage.

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

Spécifie l’URL pour l’emplacement externe utilisé pour stocker les fichiers de données (un compartiment existant auquel on accède à l’aide d’un point de terminaison de l’API compatible avec S3), où :

• bucket est le nom du compartiment.

• path est un chemin d’accès facultatif sensible à la casse (ou préfixe dans la terminologie S3) pour les fichiers dans l’emplacement de stockage Cloud (les fichiers dont le nom commence par une chaîne commune).

CREDENTIALS = ( AWS_KEY_ID = 'string' AWS_SECRET_KEY = 'string' )

Spécifie les identifiants de sécurité pour la connexion et l’accès à votre emplacement de stockage compatible S3.

STORAGE_ENDPOINT = 's3_api_compatible_endpoint'

Spécifie un domaine entièrement qualifié qui pointe vers votre point de terminaison de l’API compatible avec S3.

Note

Le point de terminaison du stockage ne doit pas inclure de nom de compartiment ; par exemple, indiquez mystorage.com au lieu de my_bucket.mystorage.com.

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

Un rôle utilisé pour exécuter cette opération doit au minimum disposer des privilèges suivants :

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¶

• Vous ne pouvez pas supprimer ni remplacer un volume externe si une ou plusieurs tables Iceberg sont associées au volume externe.

  Pour voir les tables qui dépendent d’un volume externe, vous pouvez utiliser la commande SHOW ICEBERG TABLES et une requête utilisant RESULT_SCAN qui applique un filtre sur la colonne external_volume_name.

  Note

  L’identificateur de colonne (external_volume_name) est sensible à la casse. Spécifiez l’identificateur de colonne exactement tel il apparaît dans la sortie SHOW ICEBERG TABLES.

  Par exemple :

  SHOW ICEBERG TABLES;
  
  SELECT * FROM TABLE(
    RESULT_SCAN(
        LAST_QUERY_ID()
      )
    )
    WHERE "external_volume_name" = 'my_external_volume_1';
  

  Copy

• Si vous utilisez un point de terminaison régional pour un emplacement de stockage Microsoft Fabric OneLake, utilisez la même région que votre capacité Microsoft Fabric. Il doit s’agir de la même région que celle qui héberge votre compte Snowflake.

• Pour les volumes externes S3 qui utilisent un point d’accès S3 :

  • Vous devez configurer la politique IAM pour le volume externe afin d’accorder une autorisation à votre point d’accès S3. Pour plus d’informations, voir Étape 1 : créez une politique IAM qui accorde l’accès à votre emplacement S3.

  • Les points d’accès multi-régions ne sont pas pris en charge.

• 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 modifiables en écriture 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')
        )
      )
  ALLOW_WRITES = TRUE;

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')
      )
    )
  ALLOW_WRITES = TRUE;

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'
      )
    )
  ALLOW_WRITES = TRUE;

Stockage compatible S3

Créer un volume externe qui définit un emplacement de stockage compatible avec S3. Pour plus d’informations, voir Configurer un volume externe pour un stockage compatible 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 = 'mystorage.com'
    )
  )
  ALLOW_WRITES = FALSE;