CREATE EXTERNAL VOLUME

Cria um novo volume externo para Tabelas Apache Iceberg™ na conta ou substitui um volume externo existente.

Consulte também:

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

Neste tópico:

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

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)

Nota

As chaves KMS são gerenciadas pelo proprietário do armazenamento nas instâncias do Amazon S3 ou do Google Cloud Storage. As entidades de serviço (função IAM e conta de serviço GCS) devem receber privilégios para usar chaves KMS. Para obter mais informações, consulte Criptografia de arquivos da tabela.

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:

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:

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.

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:

Privilégio

Objeto

Notas

CREATE EXTERNAL VOLUME

Conta

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

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

Importante

Volumes externos somente no armazenamento do Amazon S3: se você recriar um volume externo (usando a sintaxe CREATE OR REPLACE EXTERNAL VOLUME) sem especificar um ID externo, você deverá repetir as etapas para conceder ao usuário do gerenciamento de identidade e acesso AWS (IAM) da sua conta Snowflake as permissões de acesso necessárias no local de armazenamento S3. Para obter mais informações, consulte as instruções para recuperar o usuário AWS IAM para sua conta Snowflake em Configuração de um volume externo para Amazon S3.

  • 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:

  • 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;
Copy

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

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

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