CREATE EXTERNAL VOLUME¶

Sintaxe¶

CREATE [ OR REPLACE ] EXTERNAL VOLUME [IF NOT EXISTS]
  <name>
  STORAGE_LOCATIONS =
    (
      (
        NAME = '<storage_location_name>'
        cloudProviderParams
      )
      [, (...), ...]
    )
  [ 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_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¶

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 ) [, (...), ...] )

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.

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

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

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

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

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

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

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