ALTER TASK¶

Syntax¶

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> } | { USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = <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> ]
  [ ERROR_INTEGRATION = <integration_name> ]
  [ COMMENT = <string> ]
  [ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ]
  [ TASK_AUTO_RETRY_ATTEMPTS = <num> ]

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>

Parameter¶

name

Bezeichner für die zu ändernde Aufgabe. Wenn der Bezeichner Leerzeichen oder Sonderzeichen enthält, muss die gesamte Zeichenfolge in doppelte Anführungszeichen gesetzt werden. Bei Bezeichnern, die in doppelte Anführungszeichen eingeschlossen sind, ist auch die Groß- und Kleinschreibung zu beachten.

RESUME | SUSPEND

Gibt die Aktion an, die für die Aufgabe ausgeführt werden soll:

• RESUME ändert den Status einer angehaltenen Aufgabe in „Gestartet“. Beachten Sie, dass Konten derzeit auf maximal 30.000 gestartet Aufgaben beschränkt sind.

  Bevor Sie die Stammaufgabe Ihres Task-Graphen fortsetzen, müssen Sie alle untergeordneten Aufgaben fortsetzen. Um die untergeordneten Aufgaben der Stammaufgabe rekursiv fortzusetzen, verwenden Sie SYSTEM$TASK_DEPENDENTS_ENABLE.

• SUSPEND versetzt die Aufgabe in den Status „Angehalten“.

Wenn der Aufgabenzeitplan auf ein Intervall (number MINUTE) festgelegt ist, wird die Basisintervallzeit des Zeitplans zum Zeitpunkt des Fortsetzen der Aufgabe auf die aktuelle Zeit zurückgesetzt.

Die Basisintervallzeit startet den Intervallzähler ab der aktuellen Uhrzeit. Wenn beispielsweise ein INTERVAL-Wert von 10 festgelegt ist und die Aufgabe um 9:03 Uhr aktiviert wird, wird die Aufgabe um 9:13 Uhr, 9:23 Uhr usw. ausgeführt. Beachten Sie, dass wir nur garantieren, dass die Aufgaben nicht vor ihrem festgelegten Intervall ausgeführt werden. Im aktuellen Beispiel könnte es sein, dass die Aufgabe erstmals 9:14 Uhr ausgeführt wird, aber sie wird keinesfalls 9:12 Uhr ausgeführt.

REMOVE AFTER string [ , string , ... ]

Gibt die Namen eines oder mehrerer aktueller Vorgängeraufgaben für diese untergeordnete Aufgabe in einem Task-Graphen an.

Wenn alle Vorgänger einer untergeordneten Aufgabe entfernt werden, wird die bisherige untergeordnete Aufgabe entweder zu einer eigenständigen Aufgabe oder zu einer Stammaufgabe, je nachdem, ob andere Aufgaben diese bisher untergeordnete Aufgabe als ihren Vorgänger identifizieren. Wenn die bisher untergeordnete Aufgabe zu einer Stammaufgabe wird, wird diese Aufgabe standardmäßig angehalten und kann nur manuell fortgesetzt werden.

ADD AFTER string [ , string , ... ]

Gibt die Namen einer oder mehrerer bestehender Aufgaben an, die dieser untergeordneten Aufgabe als Vorgänger in einem Task-Graphen hinzugefügt werden sollen. Jede untergeordnete Aufgabe eines Task-Graphen wird ausgeführt, wenn die Ausführung aller Vorgängeraufgaben erfolgreich abgeschlossen wurde. Weitere Informationen dazu finden Sie in der Beschreibung des Parameters AFTER unter CREATE TASK.

Jede untergeordnete Aufgabe ist auf 100 Vorgängeraufgaben beschränkt.

SET ...

Gibt eine oder beide der folgenden Angaben an:

• Eine (oder mehrere) Eigenschaften, die für die Aufgabe festgelegt werden sollen (getrennt durch Leerzeichen, Kommas oder neue Zeilen). Weitere Informationen zu den Eigenschaften, die Sie festlegen können, finden Sie unter CREATE TASK.

• Eine durch Kommas getrennte Liste von Sitzungsparametern, die für die Sitzung festgelegt werden sollen, wenn die Aufgabe ausgeführt wird. Eine Aufgabe unterstützt alle Sitzungsparameter. Die vollständige Liste finden Sie unter Parameter.

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

  Gibt den Namen des Tags und den Wert der Tag-Zeichenfolge an.

  Der Tag-Wert ist immer eine Zeichenfolge, die maximale 256 Zeichen lang sein kann.

  Weitere Informationen zur Angabe von Tags in einer Anweisung finden Sie unter Tag-Kontingente für Objekte und Spalten.

UNSET ...

Gibt eine (oder mehrere) Eigenschaften und/oder Sitzungsparameter an, die für die Aufgabe aufgehoben werden sollen, wodurch sie auf die Standardwerte zurückgesetzt werden.

Sie können mehrere Eigenschaften/Parameter mit einer einzigen ALTER-Anweisung zurücksetzen. Dabei müssen die einzelne Eigenschaften/Parameter aber durch ein Komma getrennt werden. Wenn Sie eine Eigenschaft oder einen Parameter zurücksetzen, geben Sie nur den Namen an. Die Angabe eines Wertes für die Eigenschaft oder den Parameter gibt einen Fehler zurück.

sql

Gibt den auszuführenden SQL-Code an, wenn die Aufgabe Folgendes ausführt:

• Eine einzelne SQL-Anweisung

• Aufruf einer gespeicherten Prozedur

• Prozedurale Logik mit Snowflake Scripting

  Beachten Sie, dass Snowsight und die klassische Weboberfläche derzeit das Erstellen oder Ändern von Aufgaben zur Verwendung von Snowflake Scripting nicht unterstützen. Verwenden Sie stattdessen SnowSQL oder einen anderen Befehlszeilenclient.

Bemerkung

Überprüfen Sie, ob die SQL-Anweisung, auf die Sie in einer Aufgabe verweisen, wie erwartet ausgeführt wird, bevor Sie die Aufgabe erstellen. Aufgaben dienen der Automatisierung von SQL-Code, der bereits gründlich getestet wurden.

WHEN boolean_expr

Gibt einen booleschen SQL-Ausdruck an. Wenn eine Aufgabe ausgelöst wird (basierend auf ihrer SCHEDULE- oder AFTER-Einstellung), prüft sie die Bedingungen des Ausdrucks, um zu bestimmen, ob sie ausgeführt werden soll. Wenn die Bedingungen des Ausdrucks nicht erfüllt sind, überspringt die Aufgabe die aktuelle Ausführung. Alle Aufgaben, die diese Aufgabe als Vorgänger identifizieren, werden ebenfalls nicht ausgeführt.

Für die Validierung der Bedingungen des WHEN-Ausdrucks ist kein virtuelles Warehouse erforderlich. Die Validierung wird stattdessen in der Clouddienste-Schicht verarbeitet. Eine nominale Gebühr fällt jedes Mal an, wenn eine Aufgabe ihre WHEN-Bedingung auswertet und nicht ausgeführt wird. Die Gebühren fallen jedes Mal an, sobald die Aufgabe ausgelöst wird, bis sie ausgeführt wird. Zu diesem Zeitpunkt wird die Gebühr in Snowflake-Credits umgewandelt und der Computeressourcennutzung für die Ausführung der Aufgabe hinzugefügt.

Im Allgemeinen ist die Computezeit zur Validierung der Bedingung im Vergleich zur Ausführungszeit der Aufgabe unbedeutend. Als bewährtes Verfahren sollten Sie geplante und tatsächliche Aufgabenausführungen so eng wie möglich aufeinander abstimmen. Vermeiden Sie Aufgabenplanungen, die nicht mit den tatsächlichen Aufgabenausführungen übereinstimmen. Wenn z. B. etwa alle 24 Stunden Daten mit einem Stream in eine Tabelle eingefügt werden, planen Sie keine Aufgabe, die jede Minute auf Streamingdaten prüft. Die Kosten für die Validierung des WHEN-Ausdrucks bei jeder Ausführung sind im Allgemeinen unbedeutend, aber die Kosten sind kumulativ.

Beachten Sie, dass bei einem täglichen Verbrauch von Clouddiensten, der unter der 10%-Quote der täglichen Nutzung der Computeressourcen liegt, keine Gebühren für Clouddienste anfallen.

Derzeit werden die folgenden Funktionen für die Auswertung im SQL-Ausdruck unterstützt:

SYSTEM$STREAM_HAS_DATA

Gibt an, ob ein angegebener Stream Änderungsnachverfolgungsdaten enthält. Wird verwendet, um den aktuellen Aufgabenlauf zu überspringen, wenn der Stream keine Änderungsdaten enthält.

Wenn das Ergebnis FALSE ist, wird die Aufgabe nicht ausgeführt.

SYSTEM$GET_PREDECESSOR_RETURN_VALUE

Ruft den Rückgabewert für die Vorgängeraufgabe in einem Task-Graphen ab. Wird verwendet, um auf der Grundlage des zurückgegebenen Ergebnisses zu entscheiden, ob die Aufgabe ausgeführt werden soll.

Nutzungshinweise¶

• Das Fortsetzen oder Anhalten einer Aufgabe (mit ALTER TASK … RESUME oder ALTER TASK …SUSPEND) erfordert entweder die Berechtigung OWNERSHIP oder OPERATE für diese Aufgabe.

  Wenn eine Aufgabe fortgesetzt wird, überprüft Snowflake, ob die Rolle mit der Berechtigung OWNERSHIP für die Aufgabe auch die Berechtigung USAGE für das der Aufgabe zugewiesene Warehouse sowie die globale Berechtigung EXECUTE TASK hat. Wenn nicht, wird ein Fehler erzeugt.

  Nur Kontoadministratoren (d. h. Benutzer mit der Rolle ACCOUNTADMIN) können einer Rolle die Berechtigung EXECUTE TASK erteilen. Zur Vereinfachung der Verwendung empfehlen wir das Erstellen einer kundenspezifischen Rolle (z. B. TASKADMIN) und das Zuweisen der Berechtigung EXECUTE TASK an diese Rolle. Jede Rolle, die Berechtigungen erteilen kann (z. B. SECURITYADMIN oder jede Rolle mit der Berechtigung MANAGE GRANTS) kann diese kundenspezifische Rolle dann jeder Aufgabeneigentümerrolle zuweisen, um eine Änderung ihrer eigenen Aufgaben zu ermöglichen. Eine Anleitung zum Erstellen von kundenspezifischen Rollen und Rollenhierarchien finden Sie unter Konfigurieren der Zugriffssteuerung.

• Nur der Aufgabeneigentümer (d. h. die Rolle mit der Berechtigung OWNERSHIP für die Aufgabe) kann Eigenschaften für diese Aufgabe festlegen.

• Wenn Sie die Konfiguration ändern, können Sie keine einzelnen Schlüssel-Wert-Paare aktualisieren. Vielmehr müssen Sie die gesamte Ersatz-JSON-Zeichenfolge bereitstellen, die die komplette Konfiguration darstellt.

• Eine eigenständige Aufgabe muss angehalten werden, bevor sie geändert werden kann.

• Die Stammaufgabe in einem Task-Graphen muss angehalten werden, bevor eine Aufgabe im Task-Graphen geändert, eine untergeordnete Aufgabe angehalten/fortgesetzt oder eine untergeordnete Aufgabe hinzugefügt wird (mit ALTER TASK … AFTER).

• Ein Task-Graph ist auf maximal 1.000 Aufgaben insgesamt (einschließlich der Stammaufgabe) beschränkt, die entweder den Status „Angehalten“ oder „Fortgesetzt“ haben.

• Um alle abhängigen Aufgaben, die in einem Task-Graphen an eine Stammaufgabe gebunden sind, rekursiv fortzusetzen, fragen Sie die Funktion SYSTEM$TASK_DEPENDENTS_ENABLE ab, anstatt jede Aufgabe einzeln zu aktivieren (mit ALTER TASK … RESUME).

• Standardmäßig wird eine DML-Anweisung, die ohne explizites Starten einer Transaktion ausgeführt wird, bei Erfolg automatisch committet oder bei einem Fehler am Ende der Anweisung zurückgesetzt. Dieses Verhalten wird Autocommit genannt und mit dem Parameter AUTOCOMMIT gesteuert. Dieser Parameter muss auf TRUE gesetzt sein. Wenn der Parameter AUTOCOMMIT auf Kontoebene auf FALSE festgelegt ist, legen Sie den Parameter für die individuelle Aufgabe auf TRUE fest (mit ALTER TASK … SET AUTOCOMMIT = TRUE).

• Wenn eine Aufgabe gelöscht wird, wird jede aktuelle Ausführung der Task (d. h. ein Ausführung mit dem Status EXECUTING in der TASK_HISTORY-Ausgabe) abgeschlossen. Führen Sie die Funktion SYSTEM$USER_TASK_CANCEL_ONGOING_EXECUTIONS aus, um die Ausführung der angegebenen Aufgabe abzubrechen.

• Die Computeressourcen für die einzelnen Ausführungen einer Aufgabe werden von Snowflake (d. h. bei serverlosem Computemodell) oder von einem benutzerdefinierten virtuellen Warehouse verwaltet. Um eine Aufgabe, die auf einem Warehouse basiert, in das serverlose Computemodell umzuwandeln, entfernen Sie das Schlüsselwort WAREHOUSE.

• Wenn eine Aufgabe mit einem unerwarteten Fehler fehlschlägt, können Sie eine Benachrichtigung über den Fehler erhalten. Weitere Informationen zum Konfigurieren von Aufgabenfehlerbenachrichtigungen finden Sie unter Aktivieren von Fehlerbenachrichtigungen für Aufgaben.

• Metadaten:

  Achtung

  Kunden müssen sicherstellen, dass bei der Nutzung des Snowflake-Dienstes keine personenbezogenen Daten (außer für ein Objekt „Benutzer“), sensible Daten, exportkontrollierte Daten oder andere regulierte Daten als Metadaten eingegeben werden. Weitere Informationen dazu finden Sie unter Metadatenfelder in Snowflake.

• Hinweis zu Finalizer-Aufgaben:

  • Wenn Sie SET FINALIZE = <Name_der_Stammaufgabe> festlegen, wird eine normale Aufgabe als Finalizer-Aufgabe konfiguriert, die mit der angegebenen Stammaufgabe (root task) verbunden ist.

  • Wenn Sie UNSET FINALIZE festlegen, wird eine Finalizer-Aufgabe wieder zu einer normalen, eigenständigen Aufgabe ohne Zeitplan und Vorgänger.

  • Eine Finalizer-Aufgabe darf niemals einen Zeitplan oder Vorgänger haben. Infolgedessen steht SET FINALIZE bei einer Aufgabe in Konflikt zu SET SCHEDULE und ADD AFTER. Bei einer Aufgabe mit einem bestehenden Zeitplan oder Vorgänger schlägt die SET FINALIZE-Abfrage ebenfalls fehl. Wenn die Ziel-Stammaufgabe bereits eine Finalizer-Aufgabe hat, wird durch ALTER die alte überschrieben, sodass die Ziel-Stammaufgabe eine neue Finalizer-Aufgabe erhält.

  • Die Stammaufgabe muss angehalten werden, bevor die Finalizer-Aufgabe geändert, festgelegt oder aufgehoben werden kann.

Beispiele¶

Das folgende Beispiel leitet die Operation einer Aufgabe ein:

ALTER TASK mytask RESUME;

Im folgenden Beispiel wird eine Aufgabe in das serverlose Computemodell konvertiert und xsmall als Menge der bereitzustellenden Computeressourcen für die erste serverlose Ausführung der Aufgabe festgelegt:

ALTER TASK mytask UNSET WAREHOUSE;

ALTER TASK mytask SET USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL';

Im folgenden Beispiel werden die Sitzungsparameter TIMEZONE und CLIENT_TIMESTAMP_TYPE_MAPPING für die Sitzung festgelegt, in der die Aufgabe ausgeführt wird:

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

Das folgende Beispiel legt einen anderen Zeitplan für eine Aufgabe fest:

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

Im folgenden Beispiel werden die aktuellen Vorgängeraufgaben für die untergeordnete Aufgabe mytask (pred_task1, pred_task2) entfernt und durch eine andere Vorgängeraufgabe (pred_task3) ersetzt:

ALTER TASK mytask REMOVE AFTER pred_task1, pred_task2;

ALTER TASK mytask ADD AFTER pred_task3;

Im folgenden Beispiel wird die einer Aufgabe zugeordnete SQL-Anweisung geändert. Die Ausgabe fragt jetzt die CURRENT_VERSION-Funktion ab, wenn sie ausgeführt wird:

ALTER TASK mytask MODIFY AS SELECT CURRENT_VERSION();

Im folgenden Beispiel wird die einer Aufgabe zugeordnete WHEN-Bedingung geändert. Bei Auslösen der Aufgabe (nach einem Zeitplan oder nachdem die Vorgängeraufgabe erfolgreich beendet wurde) erfolgt die Ausführung nur dann, wenn der mystream-Stream Daten enthält:

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

Aktualisieren Sie eine bestehende Aufgabe mit einer neuen oder einer Ersatzkonfiguration.

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

Entfernen Sie die Konfiguration aus einer bestehenden Aufgabe.

ALTER TASK task_with_config UNSET CONFIG;