CREATE EXTERNAL VOLUME

Cria um novo volume externo para Tabelas 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
      )
      [, (...), ...]
    )
  [ ALLOW_WRITES = { TRUE | FALSE }]
  [ COMMENT = '<string_literal>' ]
Copy

Onde:

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

Parâmetros obrigatórios

storage_location_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 = 'name' cloudProviderParams ) [, (...), ...] )

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

Nota

  • Durante o período de versão preliminar, 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.

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 Configuração de um volume externo para tabelas Iceberg.

Amazon S3

STORAGE_PROVIDER = 'S3'

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

STORAGE_AWS_ROLE_ARN = 'iam_role'

Especifica o Amazon Resource Name (ARN) 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 acesso seguro ao Amazon S3.

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

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

  • bucket é o nome de um bucket S3 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.

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.

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 a ID de seu locatário do Office 365 ao qual pertencem as contas de armazenamento permitidas e bloqueadas. Um volume externo pode autenticar a somente um locatário, portanto, os locais de armazenamento permitidos e bloqueados devem se referir às contas de armazenamento que pertencem a este locatário.

Para encontrar sua ID de locatário, entre no portal Azure e clique em Azure Active Directory » Properties. A ID do locatário é exibida no campo Tenant ID.

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

Especifica o URL de base para seu local de armazenamento em nuvem, 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.

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.

Requisitos de controle de acesso

Uma função usada para executar este comando SQL deve ter os seguintes privilégios no mínimo:

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), 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 instruções, consulte as etapas que começam com Etapa 5: recuperar o usuário AWS IAM para sua conta Snowflake.

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