ALTER PIPE

Modifica um conjunto limitado de propriedades para um objeto de canal existente. Isso também oferece suporte às seguinte operações:

  • Pausar o canal.

  • Atualização de um canal (ou seja, a cópia de arquivos de dados especificados preparados para a fila de ingestão do Snowpipe para carregamento na tabela de destino).

  • Adicionar/substituir/remover um comentário para um canal.

  • Definir/remover um tag em um canal.

Consulte também:

CREATE PIPE, DROP PIPE , SHOW PIPES , DESCRIBE PIPE

Sintaxe

ALTER PIPE [ IF EXISTS ] <name> SET { [ objectProperties ]
                                      [ COMMENT = '<string_literal>' ] }

ALTER PIPE <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER PIPE <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

ALTER PIPE [ IF EXISTS ] <name> UNSET { <property_name> | COMMENT } [ , ... ]

ALTER PIPE [ IF EXISTS ] <name> REFRESH { [ PREFIX = '<path>' ] [ MODIFIED_AFTER = <start_time> ] }
Copy

Onde:

objectProperties ::=
  PIPE_EXECUTION_PAUSED = TRUE | FALSE
Copy

Parâmetros

name

Especifica o identificador do canal 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.

SET ...

Especifica uma (ou mais) propriedades a serem definidas para o canal (separadas por espaços em branco, vírgulas ou novas linhas):

ERROR_INTEGRATION = 'integration_name'

Obrigatório apenas ao configurar o Snowpipe para enviar notificações de erro a um serviço de mensagens em nuvem. Especifica o nome da integração da notificação utilizada para se comunicar com o serviço de mensagens. Para obter mais informações, consulte Notificações de erro do Snowpipe.

PIPE_EXECUTION_PAUSED = TRUE | FALSE

Especifica se um canal em funcionamento deve ser pausado, normalmente na preparação para transferir a propriedade do canal:

  • TRUE faz uma pausa no canal. O executionState relatado por SYSTEM$PIPE_STATUS é PAUSED. Observe que o proprietário do canal pode continuar a enviar arquivos para um canal pausado; no entanto, eles não são processados até que o canal seja retomado.

  • FALSE retoma o canal. O executionState relatado por SYSTEM$PIPE_STATUS é RUNNING.

    Nota

    Qualquer um dos seguintes cenários exige forçar um canal a ser retomado chamando a função SYSTEM$PIPE_FORCE_RESUME:

    • Transferência da propriedade do canal para outra função. Esta exigência permite ao novo proprietário avaliar o status do canal e determinar quantos arquivos estão esperando para serem carregados chamando a função SYSTEM$PIPE_STATUS.

    • Permitir que um objeto de canal que alavanca as mensagens de nuvem acione carregamentos de dados (ou seja, onde AUTO_INGEST = TRUE na definição da canal) se torne obsoleto. Um canal é considerado obsoleto quando é pausado por mais tempo do que o período de retenção limitado para mensagens de eventos recebidas para o canal (o padrão são 14 dias).

Padrão: FALSE (o canal está em execução por padrão)

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 informações sobre como especificar tags em uma instrução, consulte Cotas de tags para objetos e colunas.

COMMENT = 'string'

Adiciona um comentário ou substitui um comentário existente para o canal.

UNSET ...

Especifica uma (ou mais) propriedades a serem removidas para o canal, que as redefine aos padrões:

  • PIPE_EXECUTION_PAUSED

  • TAG tag_name [ , tag_name ... ]

  • COMMENT

Você pode redefinir várias propriedades com uma única instrução ALTER; no entanto, cada propriedade deve ser separada por uma vírgula. Ao redefinir uma propriedade/parâmetro, especificar somente o nome; especificar um valor para a propriedade retornará um erro.

REFRESH

Copia um conjunto de arquivos de dados preparados para a fila de ingestão de Snowpipe para carregamento na tabela de destino. Esta cláusula aceita um caminho opcional e pode filtrar ainda mais a lista de arquivos a serem carregados com base em uma hora de início especificada.

Nota

  • Este comando SQL só pode carregar arquivos de dados que foram preparados nos últimos 7 dias.

  • Este comando SQL verifica o histórico de carregamento tanto para o canal quanto para a tabela de destino. Como resultado, o comando coloca em fila somente aqueles arquivos que não foram carregados já usando uma das seguintes opções:

    • O mesmo canal, desde que o proprietário do canal não tenha recriado o canal depois que os arquivos foram carregados.

    • Uma instrução COPY INTO <tabela>.

Importante

A funcionalidade REFRESH destina-se ao uso em curto prazo para resolver problemas específicos quando o Snowpipe falha ao carregar um subconjunto de arquivos e não se destina ao uso regular.

PREFIX = 'path'

Caminho (ou prefixo) anexado à referência do estágio na definição do canal. O caminho limita o conjunto de arquivos a serem carregados. Somente os arquivos que começam com o caminho especificado são incluídos no carregamento de dados.

Por exemplo, suponha a definição do canal faça referência a @mystage/path1/. Se o valor path for d1/, a instrução ALTER PIPE limita os carregamentos para os arquivos no estágio @mystage com o caminho /path1/d1/. Consulte os exemplos para obter mais informações.

Note que o caminho deve ser delimitado por aspas simples.

MODIFIED_AFTER = 'start_time'

Carimbo de data/hora (no formato ISO-8601) dos arquivos de dados mais antigos a serem copiados na fila de ingestão do Snowpipe com base na data LAST_MODIFIED (isto é, data em que um arquivo foi preparado).

O valor padrão e máximo permitido é de 7 dias.

Notas de uso

  • Somente o proprietário do canal (ou seja, a função com o privilégio OWNERSHIP sobre o canal) pode definir ou remover as propriedades em um canal.

    Uma função não proprietária com os seguintes privilégios mínimos pode atualizar um canal (usando ALTER PIPE … REFRESH …):

    Privilégio

    Objeto

    Notas

    OPERATE

    Canal

    USAGE

    Estágio na definição do canal

    Somente estágios externos

    READ

    Estágio na definição do canal

    Somente estágios internos

    SELECT, INSERT

    Tabela na definição do canal

    Uma função não proprietária com o privilégio OPERATE no canal pode fazer uma pausa ou retomar um canal (usando ALTER PIPE … SET PIPE_EXECUTION_PAUSED = TRUE | FALSE).

    Operações SQL sobre objetos de esquema também exigem o privilégio USAGE no banco de dados e esquema que contém o objeto.

  • Atualmente, não é possível modificar as seguintes propriedades do canal usando uma instrução ALTER PIPE:

    Em vez disso, recrie o canal usando uma instrução CREATE OR REPLACE PIPE.

  • 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

Pausar o canal mypipe:

alter pipe mypipe SET PIPE_EXECUTION_PAUSED = true;
Copy

Adicionar ou modificar o comentário para o canal mypipe:

alter pipe mypipe SET COMMENT = "Pipe for North American sales data";
Copy

Atualização de um canal

Configurar para exemplos:

CREATE PIPE mypipe AS COPY INTO mytable FROM @mystage/path1/;
Copy

Carregar arquivos de dados do estágio @mystage/path1/ e caminho para a tabela mytable, conforme definido na definição do canal mypipe:

ALTER PIPE mypipe REFRESH;
Copy

O mesmo que o exemplo anterior, mas anexando d1 ao caminho para limitar ainda mais a lista de arquivos a serem carregados. No exemplo atual, a instrução carrega arquivos do estágio @mystage/path1/d1/ e caminho:

ALTER PIPE mypipe REFRESH PREFIX='d1/';
Copy

O mesmo que o exemplo anterior, mas apenas carregando arquivos preparados após um carimbo de data/hora especificado:

ALTER PIPE mypipe REFRESH PREFIX='d1/' MODIFIED_AFTER='2018-07-30T13:56:46-07:00';
Copy