カテゴリ：: データパイプライン DDL

ALTER TASK¶

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

こちらもご参照ください。: CREATE TASK 、 DROP TASK 、 SHOW TASKS

このトピックの内容：

構文
パラメーター
使用上の注意
例

構文¶

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

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

ALTER TASK [ IF EXISTS ] <name> SET { [ WAREHOUSE = <string> ] [ SCHEDULE = '{ <number> MINUTE | USING CRON <expr> <time_zone> }' ] }

ALTER TASK [ IF EXISTS ] <name> SET { [ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ] }

ALTER TASK [ IF EXISTS ] <name> UNSET { <property_name> | <session_parameter> } [ , ... ]

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

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

パラメーター¶

名前

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

RESUME | SUSPEND

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

RESUME は、中断されたタスクを使用可能な「開始済み」状態にします。アカウントは現在、最大10000再開（つまり、「開始済み」状態）タスクに制限されていることに注意してください。
SUSPEND は、タスクを「一時停止」状態にします。

タスクスケジュールが間隔（つまり 数値 MINUTE）に設定されている場合、あいまいさを避けるため、タスク再開時にスケジュールの 基本間隔 が現在の時刻にリセットされます。

基本間隔は、現在のクロック時間から間隔カウンターを開始します。例えば、 10 の INTERVAL 値が設定され、タスクが9：03 AM で再開する場合、タスクは9：13 AM、9：23 AMというふうに実行されます。絶対精度を確保するために最善を尽くしますが、設定間隔が発生する前にタスクが実行されないよう保証されるのみです（例えば、現在の例では、タスクは最初に9：14 AMで実行できますが、 9：12 AMでは絶対に実行されません）。

REMOVE AFTER 文字列

この子タスクの現在の先行タスクの名前を指定します。 ALTER TASK ...ADD AFTER を使用して新しい先行タスクを追加する前に、このパラメーターを使用して現在の先行タスクを指定のタスクから削除します。子タスクは自動的に中断されます。

単純なタスクのツリーでは、先行タスクが実行されて正常に終了すると、子タスクがトリガーされます。詳細については、 CREATE TASK の AFTER パラメーターの説明をご参照ください。

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

ADD AFTER 文字列

この子タスクの新しい先行タスクの名前を指定します。ALTER TASK ...REMOVE AFTERを使用して新しい先行タスクを削除した後に、このパラメーターを使用して先行タスクを指定のタスクに追加します。

SET ...

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

タスクに設定する1つ（または複数）のプロパティ（空白、カンマ、または改行で区切られます）。設定できるプロパティの詳細については、 CREATE TASK をご参照ください。
タスクの実行時にセッションに設定するセッションパラメーターのコンマ区切りリスト。タスクはすべてのセッションパラメーターをサポートします。完全なリストについては、パラメーターをご参照ください。

UNSET ...

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

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

sql

タスクの実行時に実行される単一の SQL ステートメント、またはストアドプロシージャの呼び出しを指定します。

注釈

タスクを作成する前に、タスクで参照する SQL ステートメントまたはストアドプロシージャが期待どおりに実行されることを確認します。タスクは、既に徹底的にテストされている SQL ステートメントとストアドプロシージャを自動化することを目的としています。

WHEN ブール式

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

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

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

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

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

SYSTEM$STREAM_HAS_DATA

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

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

使用上の注意¶

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

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

アカウント管理者（ ACCOUNTADMIN ロールを持つユーザー）のみが、ロールに EXECUTE TASK 権限を付与できます。使いやすくするために、カスタムロール（例： TASKADMIN）を作成し、このロールに EXECUTE TASK 権限を割り当てることをお勧めします。権限を付与できるロール（例： SECURITYADMIN または MANAGE GRANTS 権限を持つ任意のロール）は、このカスタムロールを任意のタスク所有者ロールに付与して、自身のタスクの変更を許可できます。カスタムロールとロール階層を作成する手順については、アクセス制御の構成をご参照ください。
タスクのプロパティを設定または設定解除できるのは、タスク所有者（つまり、タスクに対する OWNERSHIP 権限を持つロール）のみです。
スタンドアロンタスクは、変更する前に一時停止する必要があります。
ツリー内の任意のタスクが変更される、子タスクが一時停止または再開される、または子タスクが追加される（ 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 関数を実行します。

例¶

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

ALTER TASK mytask RESUME;

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

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

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

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

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

ALTER TASK mytask REMOVE AFTER pred_task1;

ALTER TASK mytask ADD AFTER pred_task2;

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

ALTER TASK mytask MODIFY AS SELECT CURRENT_VERSION();

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

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