CREATE EXTERNAL VOLUME¶

Sintaxe¶

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

Onde:

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

Parâmetros obrigatórios¶

name

Cadeia de caracteres que especifica o identificador (o nome) para o volume externo; deve ser única em sua conta.

O identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais detalhes, consulte Requisitos para identificadores.

STORAGE_LOCATIONS = ( ( NAME = 'storage_location_name' { cloudProviderParams | s3CompatibleStorageParams } ) [, (...), ...] )

Conjunto de locais nomeados de armazenamento em nuvem em diferentes regiões e, opcionalmente, plataformas em nuvem.

Nota

• Cada volume externo criado oferece suporte a um único local de armazenamento ativo.

• Atualmente, as tabelas entre nuvens e entre regiões não são suportadas quando você usa o Snowflake como o catálogo Iceberg.

Parâmetros opcionais¶

ALLOW_WRITES = '{ TRUE | FALSE }'

Especifica se as operações de gravação são permitidas para o volume externo; deve ser definido como TRUE para tabelas Iceberg que usam Snowflake como catálogo.

O valor deste parâmetro também deve corresponder às permissões definidas na conta de armazenamento em nuvem para cada local de armazenamento especificado.

Nota

Se você planeja usar o volume externo para tabelas Iceberg gerenciadas externamente, você pode definir este parâmetro como FALSE. O Snowflake não grava dados ou arquivos de metadados do Iceberg no seu armazenamento em nuvem quando você usa um catálogo externo do Iceberg.

Padrão: TRUE

COMMENT = 'string_literal'

Cadeia de caracteres (literal) que especifica um comentário para o volume externo.

Padrão: sem valor

Parâmetros do provedor de nuvem (cloudProviderParams)¶

Amazon S3

STORAGE_PROVIDER = '{ S3 | S3GOV }'

Especifica o provedor de armazenamento em nuvem que armazena seus arquivos de dados.

• 'S3': armazenamento S3 em regiões AWS públicas fora da China.

• 'S3GOV': armazenamento S3 em regiões governamentais AWS.

STORAGE_AWS_ROLE_ARN = 'iam_role'

Especifica o Amazon Resource Name (ARN) que diferencia maiúsculas e minúsculas da função AWS de gerenciamento de identidade e acesso (IAM) que concede privilégios no bucket S3 que contém seus arquivos de dados. Para obter mais informações, consulte Configuração de um volume externo para Amazon S3.

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

Especifica o URL de base para seu local de armazenamento em nuvem, onde:

• protocol é um dos seguintes:

  • s3 refere-se ao armazenamento S3 em regiões AWS públicas fora da China.

  • s3gov refere-se ao armazenamento S3 em regiões governamentais.

• bucket é o nome de um bucket S3 que armazena seus arquivos de dados ou o alias no estilo bucket para um ponto de acesso ao bucket S3. Para um ponto de acesso S3, você também deve especificar um valor para o parâmetro STORAGE_AWS_ACCESS_POINT_ARN.

• path é um caminho opcional que pode ser usado para proporcionar um controle granular sobre objetos no bucket.

Importante

Para criar uma tabela Iceberg que usa um catálogo externo, seus arquivos de dados Parquet e arquivos de metadados Iceberg devem estar no local STORAGE_BASE_URL.

STORAGE_AWS_ACCESS_POINT_ARN = 'string'

Especifica o nome de recurso da Amazon (ARN) para seu ponto de acesso S3. Necessário somente quando você especifica um alias de ponto de acesso S3 para seu armazenamento STORAGE_BASE_URL.

STORAGE_AWS_EXTERNAL_ID = 'external_id'

Especifica opcionalmente um ID externo que o Snowflake usa para estabelecer uma relação de confiança com AWS. Você deve especificar o mesmo ID externo na política de confiança da função IAM que você configurou para esse volume externo. Para obter mais informações, consulte Como usar um ID externo ao conceder acesso aos seus recursos do AWS a terceiros.

Se você não especificar um valor para esse parâmetro, o Snowflake gerará automaticamente um ID externo quando você criar o volume externo.

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

Especifica as propriedades necessárias para criptografar dados no volume externo.

TYPE = ...

Especifica o tipo de criptografia utilizado. Os valores possíveis são:

• 'AWS_SSE_S3' : criptografia no lado do servidor usando chaves de criptografia gerenciadas por S3. Para obter mais informações, consulte Como usar a criptografia no lado do servidor com chaves de criptografia gerenciadas pelo Amazon S3 (SSE-S3).

• 'AWS_SSE_KMS' : criptografia do lado do servidor usando chaves armazenadas em KMS. Para obter mais informações, consulte Como usar criptografia no lado do servidor com o serviço de gerenciamento de chaves AWS (SSE-KMS).

• 'NONE': sem criptografia.

KMS_KEY_ID = 'string' (aplica-se somente à criptografia AWS_SSE_KMS)

Opcionalmente especifica a ID para a chave AWS gerenciada por KMS usada para criptografar arquivos gravados no bucket. Se nenhum valor for fornecido, sua chave KMS padrão é usada para criptografar arquivos ao gravar dados.

Observe que este valor é ignorado durante a leitura dos dados.

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

Especifica se a conectividade privada de saída deve ser usada para reforçar sua postura de segurança. Para obter informações sobre como usar esse parâmetro, consulte Conectividade privada com volumes externos para AWS.

Google Cloud Storage

STORAGE_PROVIDER = 'GCS'

Especifica o provedor de armazenamento em nuvem que armazena seus arquivos de dados.

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

Especifica o URL de base para seu local de armazenamento em nuvem, onde:

• bucket é o nome de um bucket de armazenamento em nuvem que armazena seus arquivos de dados.

• path é um caminho opcional que pode ser usado para proporcionar um controle granular sobre objetos no bucket.

Importante

Para criar uma tabela Iceberg que usa um catálogo externo, seus arquivos de dados Parquet e arquivos de metadados Iceberg devem estar no local STORAGE_BASE_URL.

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

Especifica as propriedades necessárias para criptografar dados no volume externo.

TYPE = ...

Especifica o tipo de criptografia utilizado. Os valores possíveis são:

• 'GCS_SSE_KMS': criptografia do lado do servidor usando chaves armazenadas em KMS. Para obter mais informações, consulte chaves de criptografia gerenciadas pelo cliente.

• 'NONE': sem criptografia.

KMS_KEY_ID = 'string' (aplica-se somente à criptografia GCS_SSE_KMS)

Especifica o ID da chave gerenciada KMS na nuvem usada para criptografar arquivos gravados no bucket.

Observe que este valor é ignorado durante a leitura dos dados. A operação de leitura deverá ser bem-sucedida se a conta de serviço tiver permissões suficientes para os dados e quaisquer chaves KMS especificadas.

Microsoft Azure

STORAGE_PROVIDER = 'AZURE'

Especifica o provedor de armazenamento em nuvem que armazena seus arquivos de dados.

AZURE_TENANT_ID = 'tenant_id'

Especifica o ID do locatário do Office 365 ao qual o local de armazenamento pertence. Um volume externo pode ser autenticado apenas para um locatário, portanto, o local de armazenamento deve se referir a uma conta de armazenamento que pertença a esse locatário.

Para encontrar seu ID de locatário, faça login no portal do Azure e selecione Azure Active Directory » Properties. A ID do locatário é exibida no campo Tenant ID.

STORAGE_BASE_URL = 'azure://...'

Especifica o URL base para seu local de armazenamento em nuvem (com distinção entre maiúsculas e minúsculas).

• Para o Armazenamento de Blobs do Azure, especifique azure://account.blob.core.windows.net/container[/path/], onde:

  • account é o nome da sua conta do Azure; por exemplo, myaccount.

  • container é o nome de um contêiner Azure que armazena seus arquivos de dados.

  • path é um caminho opcional que pode ser usado para fornecer controle granular sobre diretórios lógicos no contêiner.

• Para o Fabric OneLake, especifique azure://[region-]onelake.dfs | blob.fabric.microsoft.com/workspace/lakehouse/Files/path/, onde:

  • region especifica opcionalmente a região do ponto de extremidade; por exemplo, westus. Se especificado, esta deve ser a mesma região usada pela sua capacidade do Microsoft Fabric e a mesma região na qual sua conta Snowflake está hospedada.

  • dfs | blob especifica o tipo de ponto de extremidade.

  • workspace é o seu ID de espaço de trabalho ou nome de espaço de trabalho do Fabric; por exemplo, cfafbeb1-8037-4d0c-896e-a46fb27ff227 ou my_workspace. É necessário usar o mesmo tipo de identificador (ID ou nome) para seu espaço de trabalho e lakehouse.

  • lakehouse é seu ID ou nome de lakehouse. É necessário usar o mesmo tipo de identificador (ID ou nome) para seu espaço de trabalho e lakehouse; por exemplo, 5b218778-e7a5-4d73-8187-f10824047715 ou my_lakehouse.Lakehouse.

  • path é um caminho para seu local de armazenamento no lakehouse e espaço de trabalho especificados.

  Recurso em versão preliminar — Aberto

  Disponível para todas as contas.

Nota

Use o prefixo azure:// e não https://.

Importante

Para criar uma tabela Iceberg que usa um catálogo externo, seus arquivos de dados Parquet e arquivos de metadados Iceberg devem estar no local STORAGE_BASE_URL.

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

Especifica se a conectividade privada de saída deve ser usada para reforçar sua postura de segurança. Para obter informações sobre como usar esse parâmetro, consulte Conectividade privada com volumes externos para Microsoft Azure.

Parâmetros de armazenamento compatíveis com o S3 (s3CompatibleStorageParams)¶

STORAGE_PROVIDER = 'S3COMPAT'

Especifica o armazenamento compatível com o S3 como seu provedor de armazenamento.

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

Especifica o URL para o local externo usado para armazenar arquivos de dados (um bucket existente acessado usando um ponto de extremidade de API compatível com S3), onde:

• bucket é o nome do bucket.

• path é um caminho opcional que diferencia maiúsculas de minúsculas (ou o prefixo na terminologia S3) para arquivos no local de armazenamento em nuvem (arquivos com nomes que começam com uma cadeia de caracteres comum).

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

Especifica as credenciais de segurança para conexão e acesso ao local de armazenamento compatível com S3.

STORAGE_ENDPOINT = 's3_api_compatible_endpoint'

Especifica um domínio totalmente qualificado que aponta para seu ponto de extremidade de API compatível com S3.

Nota

O ponto de extremidade de armazenamento não deve incluir um nome de bucket; por exemplo, especifique mystorage.com em vez de my_bucket.mystorage.com.

Requisitos de controle de acesso¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

• Não é possível remover ou substituir um volume externo se uma ou mais tabelas Iceberg estiverem associadas ao volume externo.

  Para visualizar as tabelas que dependem de um volume externo, você pode usar o comando SHOW ICEBERG TABLES e uma consulta usando RESULT_SCAN que filtra na coluna external_volume_name.

  Nota

  O identificador da coluna (external_volume_name) diferencia maiúsculas de minúsculas. Especifique o identificador da coluna exatamente como ele aparece na saída SHOW ICEBERG TABLES.

  Por exemplo:

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

  Copy

• Se você usar um ponto de extremidade regional para um local de armazenamento do Microsoft Fabric OneLake, use a mesma região que a capacidade do Microsoft Fabric. Essa também deve ser a mesma região que hospeda sua conta Snowflake.

• Para volumes externos S3 que usam um ponto de acesso S3:

  • É necessário configurar a política de IAM para que o volume externo conceda permissão ao seu ponto de acesso S3. Para obter mais informações, consulte Etapa 1: Crie uma política de IAM que conceda acesso ao seu local S3.

  • Não há suporte para pontos de acesso multirregionais.

• Em relação aos metadados:

  Atenção

  Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

• Instruções CREATE OR REPLACE <object> são atômicas. Ou seja, quando um objeto é substituído, o objeto antigo é excluído e o novo objeto é criado em uma única transação.

Exemplos¶

Os exemplos a seguir criam volumes externos que definem locais de armazenamento graváveis com diferentes provedores de nuvem:

Amazon S3

O exemplo a seguir cria um volume externo que define um local de armazenamento do Amazon S3 com criptografia:

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

O exemplo a seguir cria um volume externo que define um local de armazenamento GCS com criptografia:

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

O exemplo a seguir cria um volume externo que define um local de armazenamento do Azure com criptografia:

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;

Armazenamento compatível com S3

Crie um volume externo que defina um local de armazenamento compatível com o S3. Para obter mais informações, consulte Configuração de um volume externo para armazenamento compatível com 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;