ALTER EXTERNAL TABLE¶

Sintaxe¶

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> REFRESH [ '<relative-path>' ]

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> ADD FILES ( '<path>/[<filename>]' [ , '<path>/[<filename>'] ] )

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> REMOVE FILES ( '<path>/[<filename>]' [ , '<path>/[<filename>]' ] )

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> SET
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ] ]

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> UNSET
  TAG <tag_name> [ , <tag_name> ... ]

Partições adicionadas e removidas manualmente

ALTER EXTERNAL TABLE <name> [ IF EXISTS ] ADD PARTITION ( <part_col_name> = '<string>' [ , <part_col_name> = '<string>' ] ) LOCATION '<path>'

ALTER EXTERNAL TABLE <name> [ IF EXISTS ] DROP PARTITION LOCATION '<path>'

Copy

Parâmetros¶

name

Identificador da tabela externa a ser alterada. 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.

REFRESH [ 'relative-path' ]

Acessa os arquivos de dados preparados referenciados na definição da tabela externa e atualiza os metadados da tabela:

• Novos arquivos no caminho são adicionados aos metadados da tabela.

• As mudanças nos arquivos do caminho são atualizadas nos metadados da tabela.

• Os arquivos que não estão mais no caminho são removidos dos metadados da tabela.

Opcionalmente, especifique um caminho relativo para atualizar os metadados de um subconjunto específico dos arquivos de dados.

O uso deste parâmetro só precisa ser feito uma vez, quando a tabela externa é criada. Esta etapa sincroniza os metadados com o último conjunto de arquivos associados no estágio e no caminho na definição da tabela externa. Além disso, esta etapa garante que a tabela externa possa ler os arquivos de dados no estágio e no caminho especificados, e que nenhum arquivo tenha sido perdido na definição da tabela externa.

Nota

• Este parâmetro não é suportado por tabelas externas particionadas quando as partições são adicionadas manualmente pelo proprietário do objeto (isto é, quando PARTITION_TYPE = USER_SPECIFIED).

• Se TABLE_FORMAT = DELTA estiver definido na tabela externa, REFRESH não oferece suporte a um caminho relativo para atualizar os metadados de um subconjunto específico dos arquivos de dados.

ADD FILES

Adiciona a lista especificada de arquivos separada por vírgula aos metadados de tabela externa. Normalmente, os parâmetros ADD FILES e REMOVE FILES são usados para atualizar os metadados de tabela externa manualmente (ou seja, quando AUTO_REFRESH = FALSE). As referências do arquivo são expressas como caminhos relativos a [ WITH ] LOCATION na definição da tabela externa. Para obter mais informações, consulte CREATE EXTERNAL TABLE.

Liste o caminho e o nome do arquivo de cada arquivo.

A instrução ALTER EXTERNAL TABLE atualiza automaticamente os metadados de tabela externa e adiciona os arquivos, se presentes no local de armazenamento especificado.

Este parâmetro não é suportado por tabelas externas particionadas quando as partições são adicionadas manualmente pelo proprietário do objeto (isto é, quando PARTITION_TYPE = USER_SPECIFIED).

REMOVE FILES

Remove a lista de arquivos separada por vírgulas dos metadados da tabela externa. Normalmente, os parâmetros ADD FILES e REMOVE FILES são usados para atualizar os metadados de tabela externa manualmente (ou seja, quando AUTO_REFRESH = FALSE). As referências do arquivo são expressas como caminhos relativos a [ WITH ] LOCATION na definição da tabela externa. Para obter mais informações, consulte CREATE EXTERNAL TABLE.

Liste o caminho e o nome do arquivo de cada arquivo.

A instrução ALTER EXTERNAL TABLE atualiza automaticamente os metadados de tabela externa e remove os arquivos.

Este parâmetro não é suportado por tabelas externas particionadas quando as partições são adicionadas manualmente pelo proprietário do objeto (isto é, quando PARTITION_TYPE = USER_SPECIFIED).

SET ...

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

AUTO_REFRESH = TRUE | FALSE

Especifica se o Snowflake deve permitir acionar atualizações automáticas dos metadados da tabela externa quando os arquivos de dados novos ou atualizados estiverem disponíveis no estágio externo nomeado especificado na configuração de [ WITH ] LOCATION =.

Nota

• Você deve configurar uma notificação de evento para seu local de armazenamento para notificar o Snowflake quando dados novos ou atualizados estiverem disponíveis para leitura nos metadados de tabela externa. Para obter mais informações, consulte as instruções de seu serviço de armazenamento em nuvem:

  • Amazon S3

    Atualização automática de tabelas externas para Amazon S3

  • Google Cloud Storage

    Atualização automática de tabelas externas para Google Cloud Storage

  • Microsoft Azure

    Atualização automática de tabelas externas para o armazenamento de blobs do Azure

• Este parâmetro não é suportado por tabelas externas particionadas quando as partições são adicionadas manualmente pelo proprietário do objeto (isto é, quando PARTITION_TYPE = USER_SPECIFIED).

• A definição deste parâmetro como TRUE não é suportada para tabelas externas que referenciam arquivos de dados armazenados em um estágio externo compatível com S3.

TRUE

O Snowflake permite acionar atualizações automáticas dos metadados da tabela externa.

FALSE

O Snowflake não permite acionar atualizações automáticas dos metadados da tabela externa. Você deve atualizar manualmente os metadados da tabela externa periodicamente usando ALTER EXTERNAL TABLE … REFRESH para sincronizar os metadados com a lista atual de arquivos no caminho do estágio.

Padrão: TRUE

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

Especifica o nome da tag e o valor da cadeia de caracteres dela.

O valor de tag é sempre uma cadeia de caracteres, e o número máximo de caracteres do valor da tag é 256.

Para obter mais detalhes sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.

UNSET

• TAG tag_name [ , tag_name ... ]

Requisitos de controle de acesso¶

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

Observe que operar em qualquer objeto de um esquema também requer o privilégio USAGE no banco de dados e esquema principais.

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¶

• Somente o proprietário da tabela externa (ou seja, a função com o privilégio OWNERSHIP na tabela externa) ou superior pode executar este comando.

• Os seguintes comandos podem ser usados em transações explícitas (usando BEGIN … COMMIT):

  • ALTER EXTERNAL TABLE ... REFRESH

  • ALTER EXTERNAL TABLE ... ADD FILES

  • ALTER EXTERNAL TABLE ... REMOVE FILES

  As transações explícitas poderiam ser usadas para garantir um estado consistente ao substituir manualmente arquivos atualizados em metadados de tabelas externas.

• Adicionar ou remover colunas em uma tabela externa usando a seguinte sintaxe:

  Adicionar coluna

  ALTER TABLE <name> ADD COLUMN ( <col_name> <col_type> AS <expr> ) [, ...]
  

  Copy

  Renomear coluna

  ALTER TABLE <name> RENAME COLUMN <col_name> to <new_col_name>
  

  Copy

  Descartar coluna

  ALTER TABLE <name> DROP COLUMN <col_name>
  

  Copy

  Nota

  As colunas padrão VALUE e METADATA$FILENAME não podem ser descartadas.

  Consulte o tópico ALTER TABLE para exemplos.

• Para adicionar e descartar uma política de acesso a linhas em uma tabela externa, use o comando ALTER TABLE.

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

ALTER EXTERNAL TABLE exttable_json REFRESH;

CREATE OR REPLACE STAGE mystage
  URL='<cloud_platform>://twitter_feed/logs/'
  .. ;

-- Create the external table
-- 'daily' path includes paths in </YYYY/MM/DD/> format
CREATE OR REPLACE EXTERNAL TABLE daily_tweets
  WITH LOCATION = @twitter_feed/daily/;

-- Refresh the metadata for a single day of data files by date
ALTER EXTERNAL TABLE exttable_part REFRESH '2018/08/05/';

ALTER EXTERNAL TABLE exttable1 ADD FILES ('path1/sales4.json.gz', 'path1/sales5.json.gz');

ALTER EXTERNAL TABLE exttable1 REMOVE FILES ('path1/sales4.json.gz', 'path1/sales5.json.gz');

BEGIN;

ALTER EXTERNAL TABLE extable1 REMOVE FILES ('2019/12/log1.json.gz');

ALTER EXTERNAL TABLE extable1 ADD FILES ('2019/12/log1.json.gz');

COMMIT;

ALTER EXTERNAL TABLE et2 ADD PARTITION(col1='2022-01-24', col2='a', col3='12') LOCATION '2022/01';

ALTER EXTERNAL TABLE et2 DROP PARTITION LOCATION '2022/01';