ALTER EXTERNAL TABLE

Modifica as propriedades, colunas ou restrições de uma tabela externa existente.

Consulte também:

CREATE EXTERNAL TABLE , DROP EXTERNAL TABLE , SHOW EXTERNAL TABLES , DESCRIBE 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 }
Copy

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

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

Partições adicionadas e removidas manualmente

Use os seguintes parâmetros para adicionar ou remover partições quando o tipo de partição para a tabela externa for especificado pelo usuário (ou seja, PARTITION_TYPE = USER_SPECIFIED):

ADD PARTITION ( <part_col_name> = '<string>' [ , <part_col_name> = '<string>' , ... ] ) LOCATION '<path>'

Adicione manualmente uma partição para uma ou mais colunas de partição definidas para a tabela externa em um local especificado (ou seja, caminho).

Nota

O comprimento máximo dos nomes das colunas de partição especificadas pelo usuário é de 32 caracteres.

A adição de uma partição também adiciona quaisquer arquivos novos ou atualizados no local aos metadados da tabela externa.

DROP PARTITION LOCATION '<path>'

Descarte manualmente todas as partições em um local especificado (ou seja, caminho).

O descarte de uma partição também remove quaisquer arquivos no local dos metadados de tabela externa.

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

Tabela externa

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).

USAGE

Estágio

Obrigatório para atualizar manualmente os metadados da tabela externa:

USAGE

Formato do arquivo

Obrigatório para atualizar manualmente os metadados da tabela externa:

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

    • 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 ou para definir ou remover uma tag, use o comando ALTER TABLE.

    No entanto, você pode criar uma tabela externa com uma política de acesso a linhas e uma tag na tabela. Consulte CREATE EXTERNAL 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

Atualização manual de metadados

Atualize manualmente todo o conjunto de metadados de tabela externa com base nas mudanças nos arquivos de dados referenciados:

ALTER EXTERNAL TABLE exttable_json REFRESH;
Copy

Similar ao primeiro exemplo, mas atualizando manualmente apenas um caminho dos metadados para uma tabela externa:

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

Adição e remoção de arquivos manualmente

Adicionar uma lista explícita de arquivos aos metadados de tabela externa:

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

Remover uma lista explícita de arquivos dos metadados de tabela externa:

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

Substituir um arquivo de log atualizado de dezembro de 2019 nos metadados de tabela externa em uma transação explícita:

BEGIN;

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

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

COMMIT;
Copy

Adição e remoção de partições manualmente

Adicionar manualmente as partições em um local especificado para as colunas de partição:

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

O Snowflake adiciona as partições aos metadados de tabela externa. A operação também acrescenta aos metadados quaisquer novos arquivos de dados no local especificado.

Remover manualmente as partições de um local especificado:

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

O Snowflake remove as partições dos metadados para a tabela externa. A operação também remove quaisquer arquivos de dados no local especificado dos metadados.