ALTER 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> ] }

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

  • Instrução COPY INTO <tabela>

  • Parâmetro AWS_SNS_TOPIC

  • Parâmetro INTEGRATION

  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