ALTER EXTERNAL VOLUME

Modifica as propriedades de um volume externo existente.

Consulte também:

CREATE EXTERNAL VOLUME , DROP EXTERNAL VOLUME , SHOW EXTERNAL VOLUMES , DESCRIBE EXTERNAL VOLUME

Neste tópico:

Sintaxe

ALTER EXTERNAL VOLUME [ IF EXISTS ] <name> ADD STORAGE_LOCATION =
                                             (
                                             NAME = '<name>'
                                             cloudProviderParams
                                             )

ALTER EXTERNAL VOLUME [ IF EXISTS ] <name> REMOVE STORAGE_LOCATION '<name>'

ALTER EXTERNAL VOLUME [ IF EXISTS ] <name> SET ALLOW_WRITES = TRUE

ALTER EXTERNAL VOLUME [ IF EXISTS ] <name> SET COMMENT = '<string_literal>'
Copy

Onde:

cloudProviderParams (for Amazon S3) ::=
  STORAGE_PROVIDER = 'S3'
  STORAGE_AWS_ROLE_ARN = '<iam_role>'
  STORAGE_BASE_URL = 's3://<bucket>[/<path>/]'
  [ 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

name

Especifica o identificador do volume externo a ser alterado.

Se o identificador contiver espaços ou caracteres especiais, toda a cadeia de caracteres deverá ser delimitada por aspas duplas. Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais informações, consulte Requisitos para identificadores.

ADD STORAGE_LOCATION

Adiciona o local de armazenamento especificado à definição de volume externo. Para adicionar vários locais de armazenamento, execute uma instrução ALTER EXTERNAL VOLUME para cada local de armazenamento.

Nota

As tabelas Iceberg são gravadas e lidas no primeiro local de armazenamento do conjunto que está localizado na mesma região de sua conta Snowflake. Para visualizar a definição de volume externo e as regiões de local de armazenamento, execute DESCRIBE EXTERNAL VOLUME.

REMOVE STORAGE_LOCATION

Remove o local de armazenamento especificado da definição de volume externo. Para remover vários locais de armazenamento, execute uma instrução ALTER EXTERNAL VOLUME para cada local de armazenamento.

Nota

A instrução ALTER EXTERNAL VOLUME falhará se você tentar remover o local de armazenamento ativo usado pelas tabelas Iceberg em sua conta.

SET ...

Especifica uma ou mais propriedades/parâmetros a serem definidos para o volume externo (separados por espaços em branco, vírgulas ou novas linhas):

ALLOW_WRITES = TRUE

Especifica que 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.

COMMENT = 'string_literal'

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

Parâmetros do provedor de nuvem (cloudProviderParams)

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.

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.

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 a ID da chave gerenciada por KMS da nuvem que é usada para criptografar arquivos gravados no bucket.

Este valor é ignorado ao ler 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.

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

OWNERSHIP

Volume externo

OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

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

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.

Exemplos

O exemplo a seguir remove o local de armazenamento denominado my-us-east-1 do volume externo exvol1:

ALTER EXTERNAL VOLUME exvol1 REMOVE STORAGE_LOCATION 'my-us-east-1';
Copy

Os exemplos a seguir adicionam um local de armazenamento a um volume externo:

Amazon S3

ALTER EXTERNAL VOLUME exvol1
  ADD STORAGE_LOCATION =
    (
      NAME = 'my-s3-us-central-2'
      STORAGE_PROVIDER = 'S3'
      STORAGE_BASE_URL = 's3://my_bucket_us_central-1/'
      STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/myrole'
    );
Copy

Google Cloud Storage

ALTER EXTERNAL VOLUME exvol2
  ADD STORAGE_LOCATION =
    (
      NAME = 'my-gcs-europe-west4'
      STORAGE_PROVIDER = 'GCS'
      STORAGE_BASE_URL = 'gcs://my_bucket_europe-west4/'
    );
Copy

Microsoft Azure

ALTER EXTERNAL VOLUME exvol3
  ADD STORAGE_LOCATION =
    (
      NAME = 'my-azure-japaneast'
      STORAGE_PROVIDER = 'AZURE'
      STORAGE_BASE_URL = 'azure://sfcdev1.blob.core.windows.net/my_container_japaneast/'
      AZURE_TENANT_ID = 'a9876545-4321-987b-b23c-2kz436789d0'
    );
Copy