ALTER TASK

既存のタスクのプロパティを変更します。

こちらもご参照ください。

CREATE TASK、 DROP TASK、 SHOW TASKS、 DESCRIBE TASK

構文

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>
Copy

パラメーター

name

変更するタスクの識別子。識別子にスペースまたは特殊文字が含まれる場合、文字列全体を二重引用符で囲む必要があります。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

RESUME | SUSPEND

タスクで実行するアクションを指定します。

  • RESUME は、中断されたタスクを「開始」状態にします。アカウントは現在、最大30000件の開始タスクに制限されていることに注意してください。

    タスクグラフのルートタスクを再開する前に、すべての子タスクを再開します。ルートタスクの子タスクを再帰的に再開するには、 SYSTEM$TASK_DEPENDENTS_ENABLE を使用します。

  • SUSPEND は、タスクを「一時停止」状態にします。

タスクスケジュールが間隔（number MINUTE）に設定されている場合は、スケジュールの 基本間隔時間 がタスク再開時の現在の時刻にリセットされます。

基本間隔時間は、現在のクロックタイムから間隔カウンターを開始します。例えば、 10 の INTERVAL 値が設定され、タスクが9：03 AM で再開する場合、タスクは9：13 AM、9：23 AMというふうに実行されます。タスクは、設定されたインターバルが発生する 前に 実行されないことだけが保証されることに注意してください。現在の例では、タスクは最初9:14 AM に実行され、9:12 AM には実行されません。

REMOVE AFTER string [ , string , ... ]

タスクグラフ で、この子タスクに対する現在の先行タスク1つ以上の名前を指定します。

子タスクの先行タスクすべてが削除されると、他のタスクが元の子タスクを先行タスクとして識別するかどうかに応じて、元の子タスクはスタンドアロンタスクまたはルートタスクになります。前の子タスクがルートタスクになる場合、このタスクはデフォルトで中断されているため、手動で再開する必要があります。

ADD AFTER string [ , string , ... ]

タスクグラフ で、この子タスクの先行タスクとして既存のタスク1つ以上の名前を指定します。各子タスクは、すべての先行タスクが正常に実行を終了したときに実行されます。詳細については、 CREATE TASK の AFTER パラメーターの説明をご参照ください。

各子タスクは、100先行タスクに制限されています。

SET ...

次のいずれかまたは両方を指定します。

  • タスクに設定する1つ（または複数）のプロパティ（空白、カンマ、または改行で区切られます）。設定できるプロパティの詳細については、 CREATE TASK をご参照ください。

  • タスクの実行時にセッションに設定するセッションパラメーターのコンマ区切りリスト。タスクはすべてのセッションパラメーターをサポートします。完全なリストについては、 パラメーター をご参照ください。

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

    タグ の名前とタグ文字列の値を指定します。

    タグ値は常に文字列であり、タグ値の最大文字数は256です。

    ステートメントでのタグの指定に関する情報については、 オブジェクトおよび列のタグクォータ をご参照ください。

UNSET ...

タスクの設定を解除する1つ（または複数）のプロパティやセッションパラメーターを指定します。これにより、デフォルトにリセットされます。

単一の ALTER ステートメントで複数のプロパティ/パラメーターをリセットできます。ただし、各プロパティ/パラメーターはカンマで区切る 必要があります 。プロパティ/パラメーターをリセットするときは、名前のみを指定します。プロパティ/パラメーターの値を指定すると、エラーが返されます。

sql

タスクの実行時に実行する SQL コードを指定します。

  • 単一の SQL ステートメント

  • ストアドプロシージャへの呼び出し

  • Snowflakeスクリプト を使用した手続き型ロジック

    現在、 Snowsight と Classic Console では、Snowflakeスクリプトを使用するためのタスクの作成または変更をサポートしていないことに注意してください。代わりに、 SnowSQL または別のコマンドラインクライアントを使用してください。

注釈

タスクを作成する 前に 、タスクで参照する SQL コードが期待どおりに実行されることを確認します。タスクは、すでに徹底的にテストされている SQL コードの自動化を目的としています。

WHEN boolean_expr

ブール SQL 式を指定します。（ SCHEDULE または AFTER 設定に基づいて）タスクがトリガーされると、式の条件を検証して、実行するかどうかを決定します。式の条件が 満たされない 場合、タスクは現在の実行をスキップします。このタスクを先行タスクとして識別するタスクも実行されません。

WHEN 式の条件を検証するために、仮想ウェアハウスは必要ありません。代わりに、検証はクラウドサービスレイヤーで処理されます。タスクが WHEN 条件を評価して実行しないたびに、わずかな料金が発生します。タスクが実行されるまで、タスクがトリガーされるたびに料金が累積されます。その時点で、料金はSnowflakeクレジットに変換され、タスク実行のコンピューティングリソース使用量に追加されます。

一般に、条件を検証するための計算時間は、タスクの実行時間と比較して重要ではありません。ベストプラクティスとして、スケジュールされたタスクと実際のタスクの実行を可能な限り一致させます。実際のタスク実行と大幅に同期していないタスクスケジュールは避けてください。たとえば、データがおよそ24時間ごとにストリームのあるテーブルに挿入される場合、毎分ストリームデータをチェックするタスクはスケジュールしないでください。各実行で WHEN 式を検証するための料金は、通常は重要ではありませんが、料金は累積されます。

コンピューティングリソース1日あたりの使用量の10%クォータ を下回るクラウドサービス1日あたりの消費量は、クラウドサービスの料金に累積されません。

現在、次の関数は SQL 式の評価でサポートされています。

SYSTEM$STREAM_HAS_DATA

指定されたストリームに変更追跡データが含まれているかどうかを示します。ストリームに変更データが含まれていない場合、現在のタスクの実行をスキップするために使用されます。

結果が FALSE の場合、タスクは実行されません。

SYSTEM$GET_PREDECESSOR_RETURN_VALUE

タスクグラフで先行タスクの戻り値を取得します。返された結果に基づいて、タスクを実行すべきかどうかを決定するために使用されます。

使用上の注意

  • タスクの再開または中断（ ALTER TASK ... RESUME または ALTER TASK ... SUSPEND をそれぞれ使用）には、タスクの OWNERSHIP または OPERATE 権限が必要です。

    タスクが再開されると、Snowflakeは、タスクに対する OWNERSHIP 権限を持つロールが、タスクに割り当てられたウェアハウスに対する USAGE 権限、およびグローバル EXECUTE TASK 権限を持っていることを確認します。それ以外の場合は、エラーが生成されます。

    アカウント管理者（ ACCOUNTADMIN ロールを持つユーザー）のみが、ロールに EXECUTE TASK 権限を付与できます。使いやすくするために、カスタムロール（例： TASKADMIN）を作成し、このロールに EXECUTE TASK 権限を割り当てることをお勧めします。権限を付与できるロール（例： SECURITYADMIN または MANAGE GRANTS 権限を持つ任意のロール）は、このカスタムロールを任意のタスク所有者ロールに付与して、自身のタスクの変更を許可できます。カスタムロールとロール階層を作成する手順については、 アクセス制御の構成 をご参照ください。

  • タスクのプロパティを設定または設定解除できるのは、タスク所有者（つまり、タスクに対する OWNERSHIP 権限を持つロール）のみです。

  • 構成を変更する場合に、個別のキー値ペアを更新することはできません。そうではなく、完全な構成を表す置換用JSON文字列全体を提供する必要があります。

  • スタンドアロンタスクは、変更する前に中断する必要があります。

  • タスクグラフ内の いずれかの タスクが変更されるか、子タスクが中断または再開されるか、子タスクが追加される（ALTER TASK ... AFTER を使用）前に、 タスクグラフ 内のルートタスクを中断する必要があります。

  • タスクグラフは、再開状態または中断状態のいずれかにおいて、合計で最大1000タスク（ルートタスクを含む）に制限されます。

  • タスクグラフでルートタスクに関連付けられたすべての依存タスクを再帰的に再開するには、各タスクを個別に有効にするのではなく、 SYSTEM$TASK_DEPENDENTS_ENABLE 関数をクエリします（ALTER TASK ... RESUME を使用）。

  • デフォルトでは、トランザクションを明示的に開始せずに実行された DML ステートメントは、成功時には自動的にコミットされ、失敗時にはステートメントの最後でロールバックされます。この動作は 自動コミット と呼ばれ、 AUTOCOMMIT パラメーターで制御されます。このパラメーターは TRUE に設定する 必要があります。アカウントレベルで AUTOCOMMIT パラメーターが FALSE に設定されている場合、個々のタスクのパラメーターを TRUE に設定します（ ALTER TASK ... SET AUTOCOMMIT = TRUE を使用）。

  • タスクが中断されると、タスクの現在の実行（つまり、 TASK_HISTORY 出力での EXECUTING 状態の実行）が完了します。指定されたタスクの実行を中止するには、 SYSTEM$USER_TASK_CANCEL_ONGOING_EXECUTIONS 関数を実行します。

  • タスクの個々の実行に対するコンピューティングリソースは、Snowflake（つまり、サーバーレスコンピューティングモデル）またはユーザー指定の仮想ウェアハウスの いずれか によって管理されます。ウェアハウスに依存するタスクをサーバーレスコンピューティングモデルに変換するには、 WAREHOUSE の設定を解除します。

  • タスクが予期しないエラーで失敗した場合、エラーに関する通知を受け取ることができます。タスクエラー通知の構成の詳細については、 タスクのエラー通知の有効化 をご参照ください。

  • メタデータについて:

    注意

    Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。

  • ファイナライザータスクについて:

    • SET FINALIZE = <ルートタスク名> を指定すると、通常のタスクは指定されたルートタスクに関連するファイナライザータスクになるように設定されます。

    • UNSET FINALIZE を指定すると、ファイナライザータスクはスケジュールも先行タスクもない通常のスタンドアロンタスクに戻ります。

    • ファイナライザータスクには、スケジュールや先行タスクを指定できません。その結果、タスクへの SET FINALIZE は SET SCHEDULE と ADD AFTER と競合します。既存のスケジュールや先行タスクがあるタスクも SET FINALIZE クエリに失敗します。ターゲットルートタスクに既にファイナライザータスクがある場合、ALTER は古いファイナライザータスクを上書きし、ターゲットルートタスクに新しいファイナライザータスクが指定されます。

    • ルートタスクは、ファイナライザータスクが変更、設定、設定解除される前に中断される必要があります。

例

次の例では、タスクの操作を開始します。

ALTER TASK mytask RESUME;
Copy

次の例では、タスクをサーバーレスコンピューティングモデルに変換し、タスクの最初のサーバーレス実行にプロビジョニングするコンピューティングリソースの量として xsmall を設定します。

ALTER TASK mytask UNSET WAREHOUSE;

ALTER TASK mytask SET USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 'XSMALL';
Copy

次の例では、タスクが実行されるセッションの TIMEZONE および CLIENT_TIMESTAMP_TYPE_MAPPING セッションパラメーターを設定します。

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

次の例では、タスクに異なるスケジュールを設定します。

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

次の例では、 mytask 子タスク（pred_task1、 pred_task2）の現在の先行タスクを削除し、別の先行タスク（pred_task3）に置き換えます。

ALTER TASK mytask REMOVE AFTER pred_task1, pred_task2;

ALTER TASK mytask ADD AFTER pred_task3;
Copy

次の例では、タスクに関連付けられた SQL ステートメントを変更します。タスクは、実行時に CURRENT_VERSION 関数をクエリするようになりました。

ALTER TASK mytask MODIFY AS SELECT CURRENT_VERSION();
Copy

次の例では、タスクに関連付けられた WHEN 条件を変更します。トリガー（スケジュールにより、または先行タスクが正常に実行された後）されると、 mystream ストリームにデータが含まれる場合にのみタスクが実行されるようになりました。

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

新規または置換された構成で既存のタスクを更新します。

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

既存のタスクから構成を削除します。

ALTER TASK task_with_config UNSET CONFIG;
Copy
言語: 日本語