ALTER TASK¶

Modifica as propriedades para uma tarefa existente.

Consulte também:: CREATE TASK , DROP TASK , SHOW TASKS , DESCRIBE TASK

Sintaxe¶

ALTER TASK [ IF EXISTS ] <name> RESUME | SUSPEND

ALTER TASK [ IF EXISTS ] <name> REMOVE AFTER <string> [ , <string> , ... ] | ADD AFTER <string> [ , <string> , ... ]

ALTER TASK [ IF EXISTS ] <name> SET
  [ WAREHOUSE = <string> ]
  [ SCHEDULE = '{ <number> MINUTE | USING CRON <expr> <time_zone> }' ]
  [ CONFIG = <configuration_string> ]
  [ ALLOW_OVERLAPPING_EXECUTION = TRUE | FALSE ]
  [ USER_TASK_TIMEOUT_MS = <num> ]
  [ SUSPEND_TASK_AFTER_NUM_FAILURES = <num> ]
  [ COMMENT = <string> ]
  [ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ]

ALTER TASK [ IF EXISTS ] <name> UNSET
  [ WAREHOUSE ]
  [ SCHEDULE ]
  [ CONFIG ]
  [ ALLOW_OVERLAPPING_EXECUTION ]
  [ USER_TASK_TIMEOUT_MS ]
  [ SUSPEND_TASK_AFTER_NUM_FAILURES ]
  [ COMMENT ]
  [ <session_parameter> [ , <session_parameter> ... ] ]
  [ , ... ]

ALTER TASK [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

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

ALTER TASK [ IF EXISTS ] <name> SET FINALIZE = <string>

ALTER TASK [ IF EXISTS ] <name> UNSET FINALIZE

ALTER TASK [ IF EXISTS ] <name> MODIFY AS <sql>

ALTER TASK [ IF EXISTS ] <name> MODIFY WHEN <boolean_expr>

Copy

Parâmetros¶

name

Identificador para a tarefa 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.

RESUME | SUSPEND

Especifica a ação a ser executada na tarefa:

RESUME traz uma tarefa suspensa para um estado ‘Iniciado’ utilizável. Observe que as contas estão atualmente limitadas a um máximo de 30.000 tarefas retomadas (isto é, em um estado ‘Iniciado’).
SUSPEND coloca a tarefa em um estado ‘Suspenso’.

Se a programação da tarefa for definida para um intervalo (isto é, number MINUTE), então para evitar ambiguidade, o tempo de intervalo base para a programação será redefinido para a hora atual quando a tarefa é retomada.

O tempo de intervalo base inicia o contador de intervalo a partir da hora atual do relógio. Por exemplo, se um valor INTERVAL de 10 for definido e a tarefa for retomada às 9:03h AM, então a tarefa será executada às 9:13h AM, 9:23h AM e assim por diante. Note que fazemos o melhor para assegurar precisão absoluta, mas apenas garantimos que as tarefas não sejam executadas antes que ocorra seu intervalo definido (por exemplo, no exemplo atual, a tarefa poderia ser executada primeiro às 9:14h AM, mas definitivamente não será executada às 9:12h AM).

REMOVE AFTER string [ , string , ... ]

Especifica os nomes de uma ou mais tarefas predecessoras atuais para essa tarefa filho em um DAG de tarefas.

Quando todos os predecessores de uma tarefa filho são removidos, a antiga tarefa filho torna-se uma tarefa independente ou uma tarefa raiz, dependendo de se outras tarefas identificam essa tarefa filho antiga como predecessor. Se a antiga tarefa filho tornar-se uma tarefa raiz, esta tarefa será suspensa por padrão e deverá ser retomada manualmente.

ADD AFTER string [ , string , ... ]

Especifica os nomes de uma ou mais tarefas existentes para adicionar como predecessores para essa tarefa filho em um DAG de tarefas. Cada tarefa filho em um DAG é executada quando todas as tarefas predecessoras terminam com sucesso. Para obter mais informações, consulte a descrição do parâmetro AFTER em CREATE TASK.

Cada tarefa filho é limitada a 100 tarefas predecessoras.

SET ...

Especifica uma ou as duas coisas a seguir:

Uma (ou mais) propriedades a serem definidas para a tarefa (separadas por espaços em branco, vírgulas ou novas linhas). Para obter mais detalhes sobre as propriedades que você pode definir, consulte CREATE TASK.
Uma lista separada por vírgula dos parâmetros da sessão a serem definidos para a sessão quando a tarefa for executada. Uma tarefa oferece suporte a todos os parâmetros da sessão. Para a lista completa, consulte Parâmetros.
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 ...

Especifica uma (ou mais) propriedades e/ou parâmetros de sessão a serem removidos para a tarefa, o que os restabelece para os padrões.

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

sql

Especifica o código SQL a ser executado quando a tarefa é executada:

Instrução SQL única
Chamada de um procedimento armazenado
Lógica de procedimentos usando Script Snowflake

Observe que, atualmente, Snowsight e a Classic Console não oferecem suporte à criação ou modificação de tarefas para usar o Script Snowflake. Em vez disso, use SnowSQL ou outro cliente de linha de comando.

Nota

Verifique se o código SQL ao qual você se refere em uma tarefa é executado como esperado antes de você criar a tarefa. As tarefas destinam-se a automatizar o códigos SQL que já foram testados exaustivamente.

WHEN boolean_expr

Especifica uma expressão booleana SQL. Quando uma tarefa é acionada (com base em sua configuração SCHEDULE ou AFTER), ela valida as condições da expressão para determinar se deve ser executada. Se as condições da expressão não forem atendidas, então a tarefa pulará a execução atual. Qualquer tarefa que identifique esta tarefa como predecessora também não é executada.

A validação das condições da expressão WHEN não requer um warehouse virtual. Em vez disso, a validação é processada na camada de serviços de nuvem. Uma taxa nominal acumula cada vez que uma tarefa avalia sua condição WHEN e não é executada. As taxas se acumulam cada vez que a tarefa é acionada até que ela funcione. Naquele momento, a taxa é convertida em créditos do Snowflake e adicionada ao uso de recursos de computação para a execução da tarefa.

Geralmente o tempo de computação para validar a condição é insignificante em comparação com o tempo de execução da tarefa. Como prática recomendada, o alinhamento das tarefas programadas e das reais é feito o mais próximo possível. Evite agendamentos de tarefas que estejam muito fora de sincronia com a execução de tarefas reais. Por exemplo, se os dados forem inseridos em uma tabela com um fluxo aproximadamente a cada 24 horas, não programe uma tarefa que verifique os dados do fluxo a cada minuto. A taxa para validar a expressão WHEN com cada execução é geralmente insignificante, mas as taxas são cumulativas.

Observe que o consumo diário de serviços de nuvem que fica abaixo da cota de 10% do uso diário dos recursos de computação não acumula nenhuma taxa de serviços de nuvem.

Atualmente, as seguintes funções são suportadas para avaliação na expressão SQL:

SYSTEM$STREAM_HAS_DATA

Indica se um fluxo especificado contém dados de rastreamento de alterações. Usado para pular a execução da tarefa atual se o fluxo não contiver dados de mudança.

Se o resultado for FALSE, então a tarefa não é executada.

SYSTEM$GET_PREDECESSOR_RETURN_VALUE

Recupera o valor de retorno da tarefa anterior em um DAG de tarefas. Usado para tomar decisões sobre se a tarefa deve ser executada com base no resultado retornado.

Notas de uso¶

Retomar ou suspender uma tarefa (usando ALTER TASK … RESUME ou ALTER TASK … SUSPEND, respectivamente) requer o privilégio OWNERSHIP ou OPERATE na tarefa.

Quando uma tarefa é retomada, o Snowflake verifica se a função com o privilégio OWNERSHIP na tarefa também tem o privilégio USAGE no warehouse atribuído à tarefa, assim como o privilégio global EXECUTE TASK; caso contrário, um erro será gerado.

Somente os administradores de conta (usuários com a função ACCOUNTADMIN) podem conceder o privilégio EXECUTE TASK a uma função. Para facilitar o uso, recomendamos a criação de uma função personalizada (por exemplo, TASKADMIN) e a atribuição do privilégio EXECUTE TASK a esta função. Qualquer função que possa conceder privilégios (por exemplo, SECURITYADMIN ou qualquer função com o privilégio MANAGE GRANTS) pode então conceder esta função personalizada a qualquer função de proprietário da tarefa para permitir a alteração de suas próprias tarefas. Para instruções sobre como criar funções e hierarquias de funções personalizadas, consulte Configuração do controle de acesso.
Somente o proprietário da tarefa (ou seja, a função com o privilégio OWNERSHIP sobre a tarefa) pode definir ou remover as propriedades em uma tarefa.
Ao alterar a configuração, você não pode atualizar pares chave-valor individuais. Em vez disso, você deve fornecer toda a cadeia de caracteres json de substituição que representa a configuração completa.
Uma tarefa autônoma deve ser suspensa antes que possa ser modificada.
A tarefa raiz em um DAG de tarefas deve ser suspensa antes que qualquer tarefa no DAG seja modificada, uma tarefa filha seja suspensa ou retomada ou uma tarefa filho seja adicionada (usando ALTER TASK … AFTER).
Um DAG é limitado a um máximo de 1.000 tarefas no total (incluindo a tarefa raiz) em um estado resumido ou suspenso.
Para retomar recursivamente todas as tarefas dependentes vinculadas a uma tarefa raiz em um DAG, consulte a função SYSTEM$TASK_DEPENDENTS_ENABLE em vez de habilitar cada tarefa individualmente (usando ALTER TASK … RESUME).
Por padrão, uma instrução DML executada sem iniciar explicitamente uma transação é automaticamente confirmada com o sucesso ou revertida com o fracasso no fim da instrução. Este comportamento é chamado de confirmação automática e é controlado com o parâmetro AUTOCOMMIT. Este parâmetro deve ser definido como TRUE. Se o parâmetro AUTOCOMMIT for definido como FALSE no nível de conta, então defina o parâmetro como TRUE para a tarefa individual (usando ALTER TASK … SET AUTOCOMMIT = TRUE).
Quando uma tarefa é suspensa, qualquer execução atual da tarefa (ou seja, uma execução com um estado EXECUTING na saída TASK_HISTORY) é concluída. Para interromper a execução da tarefa especificada, execute a função SYSTEM$USER_TASK_CANCEL_ONGOING_EXECUTIONS.
Os recursos de computação para execuções individuais de uma tarefa podem ser tanto gerenciados pelo Snowflake (ou seja, modelo de computação sem servidor) quanto por um warehouse virtual especificado pelo usuário. Para converter uma tarefa que depende de um warehouse no modelo de computação sem servidor, remova o WAREHOUSE.

Nota

O modelo de computação sem servidor é suportado como um recurso em versão preliminar.
Se uma tarefa falhar com um erro inesperado, você poderá receber uma notificação sobre o erro. Para obter mais informações sobre a configuração de notificações de erro de tarefa, consulte Habilitação de notificações de erro para tarefas.
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.
Em relação à tarefa finalizadora:
- Quando você SET FINALIZE = <nome da tarefa raiz>, uma tarefa normal é configurada para ser uma tarefa finalizadora associada à tarefa raiz especificada.
- Quando você UNSET FINALIZE, uma tarefa do finalizador volta a ser uma tarefa autônoma normal, sem agendamento nem predecessor.
- Uma tarefa finalizadora nunca deve ter um agendamento ou predecessor. Como resultado, SET FINALIZE para uma tarefa entra em conflito com SET SCHEDULE e ADD AFTER. Uma tarefa com um agendamento ou predecessor existente também falhará na consulta SET FINALIZE. Se a tarefa raiz de destino já tiver uma tarefa finalizadora, o ALTER substituirá a antiga para que a tarefa raiz de destino tenha uma nova tarefa finalizadora.
- A tarefa raiz deve ser suspensa antes que a tarefa finalizadora seja modificada, definida ou desativada.

Exemplos¶

O exemplo a seguir inicia a operação de uma tarefa:

ALTER TASK mytask RESUME;

Copy

O exemplo a seguir converte uma tarefa no modelo de computação sem servidor e define xsmall como a quantidade de recursos de computação a serem provisionados para as primeiras execuções sem servidor da tarefa:

ALTER TASK mytask UNSET WAREHOUSE;

ALTER TASK mytask SET USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL';

Copy

O exemplo a seguir define os parâmetros da sessão TIMEZONE e CLIENT_TIMESTAMP_TYPE_MAPPING para a sessão em que a tarefa é executada:

ALTER TASK mytask SET TIMEZONE = 'America/Los_Angeles', CLIENT_TIMESTAMP_TYPE_MAPPING = TIMESTAMP_LTZ;

Copy

O exemplo a seguir estabelece um cronograma diferente para uma tarefa:

ALTER TASK mytask SET SCHEDULE = 'USING CRON */3 * * * * UTC';

Copy

O exemplo a seguir remove as tarefas precedentes atuais da mytask tarefa filho (pred_task1, pred_task2) e as substitui por uma tarefa precedente diferente (pred_task3):

ALTER TASK mytask REMOVE AFTER pred_task1, pred_task2;

ALTER TASK mytask ADD AFTER pred_task3;

Copy

O exemplo a seguir altera a instrução SQL associada a uma tarefa. A tarefa agora consulta a função CURRENT_VERSION quando ela é executada:

ALTER TASK mytask MODIFY AS SELECT CURRENT_VERSION();

Copy

O exemplo a seguir modifica a condição WHEN associada a uma tarefa. Quando acionada (em uma programação ou após a execução bem sucedida da tarefa anterior), a tarefa agora só será executada quando o fluxo mystream contiver dados:

ALTER TASK mytask MODIFY WHEN SYSTEM$STREAM_HAS_DATA('MYSTREAM');

Copy

Atualize uma tarefa existente com uma configuração nova ou substituta.

ALTER TASK task_with_config SET
      CONFIG=$${"output_directory": "/temp/prod_directory/", "environment": "prod"}$$;

Copy

Remova a configuração de uma tarefa existente.

ALTER TASK task_with_config UNSET CONFIG;

Copy