カテゴリ：

データパイプライン DDL

CREATE TASK

現在/指定されたスキーマに新しいタスクを作成するか、既存のタスクを置き換えます。

このコマンドは、次のバリアントもサポートしています。

• CREATE TASK ... CLONE （既存のタスクのクローンを作成）

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

ALTER TASK 、 DROP TASK 、 SHOW TASKS

このトピックの内容：

構文

CREATE [ OR REPLACE ] TASK [ IF NOT EXISTS ] <name>
  WAREHOUSE = <string>
  [ SCHEDULE = '{ <num> MINUTE | USING CRON <expr> <time_zone> }' ]
  [ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ]
  [ USER_TASK_TIMEOUT_MS = <num> ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ AFTER <string> ]
[ WHEN <boolean_expr> ]
AS
  <sql>

バリアント構文

CREATE TASK ... CLONE

同じパラメーター値で新しいタスクを作成します。

CREATE [ OR REPLACE ] TASK <name> CLONE <source_task>
  [ COPY GRANTS ]
  [ ... ]

詳細については、 CREATE <オブジェクト> ... CLONE をご参照ください。

必須パラメーター

名前

タスクの識別子（名前）を指定する文字列。タスクが作成されるスキーマに対して一意である必要があります。

また、識別子はアルファベット文字で始まる必要があり、識別子文字列全体が二重引用符で囲まれていない限り、スペースや特殊文字を含めることはできません（例： "My object"）。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

詳細については、 識別子の要件 をご参照ください。

WAREHOUSE = 文字列

タスクの実行に使用される仮想ウェアハウスを指定します。

SQL

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

注釈

SQL ステートメントまたはストアドプロシージャは、それ自体で実行可能で なければなりません。タスクを作成する 前 に、 SQL が期待どおりに実行されることを確認することを強くお勧めします。タスクは、すでに徹底的にテストされている SQL ステートメントとストアドプロシージャを自動化することを目的としています。

オプションのパラメーター

SCHEDULE ...

タスクを定期的に実行するスケジュールを指定します。

注釈

ルートタスクにスケジュールを定義する 必要があります。定義しないと、タスクが実行されません。

タスクの単純なツリー内の子タスク（つまり、AFTERパラメーターを使用して設定された先行タスクを持つタスク）のスケジュールを指定することは できません。

• USING CRON 式 タイムゾーン

  タスクを定期的に実行するためのcron式とタイムゾーンを指定します。標準のcronユーティリティ構文のサブセットをサポートします。

  タイムゾーンのリストについては、 tzデータベースタイムゾーンのリスト （Wikipedia）をご参照ください。

  cron式は、次のフィールドで構成されます。

  # __________ minute (0-59)
  # | ________ hour (0-23)
  # | | ______ day of month (1-31, or L)
  # | | | ____ month (1-12, JAN-DEC)
  # | | | | _ day of week (0-6, SUN-SAT, or L)
  # | | | | |
  # | | | | |
    * * * * *
  

  次の特殊文字がサポートされています。

  *

  ワイルドカード。フィールドのオカレンスを指定します。

  L

  「最後」の略。曜日フィールドで使用すると、特定の月の「最後の金曜日」（「5L」）などの構造を指定できます。月の日フィールドでは、月の最後の日を指定します。

  /n

  特定の時間単位の nth インスタンスを示します。例えば、月フィールドに 4/3 が指定されている場合、タスクは4月、7月、および10月にスケジュールされます（つまり、4番目の月から始まる3か月ごと）。

  注釈

  • cron式は現在、指定されたタイムゾーンに対してのみ評価します。アカウントの TIMEZONE パラメーター値を変更（またはユーザーレベルまたはセッションレベルで値を設定）しても、タスクのタイムゾーンは 変更されません 。

  • cron式は、タスクのすべての 有効 実行時間を定義します。Snowflakeは、このスケジュールに基づいてタスクを実行しようとします。ただし、次の有効な実行時間が始まる前に前の実行が完了していない場合、有効な実行時間はスキップされます。

  • 特定の月と曜日の両方がcron式に含まれている場合、タスクは月または曜日の いずれか を満たす日にスケジュールされます。例えば、 SCHEDULE = 'USING CRON 0 0 10-20 * TUE,THU UTC' は、月の10日から20日、およびそれらの日付以外の火曜日または木曜日に、 0AM でタスクをスケジュールします。

• 数値 MINUTE

  タスクの実行間に挿入される待機時間の間隔（分単位）を指定します。正の整数のみを受け入れます。

  数値 M 構文もサポートしています。

  あいまいさを避けるために、次の場合には 基本間隔時間 が設定されます。

  • タスクが再開された場合（ ALTER TASK ... RESUME を使用） または

  • 異なる間隔が設定されている場合（ ALTER TASK ... SET SCHEDULE を使用）

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

セッションパラメーター = 値 [ , セッションパラメーター = 値 ... ]

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

USER_TASK_TIMEOUT_MS = 数値

タスクがタイムアウトするまでの1回の実行の制限時間（ミリ秒単位）を指定します。

注釈

タスクの制限時間を大幅に増やす前に、タスクによって開始された SQL ステートメントを最適化できるか（ステートメントを書き換えるか、ストアドプロシージャを使用して）、ウェアハウスのサイズを増やす必要があるかどうかを検討してください。

値： 0 - 86400000 （1日）。

デフォルト： 3600000 （1時間）

COPY GRANTS

次の CREATE TASK バリアントのいずれかを使用して新しいタスクが作成されるときに、元のタスクからのアクセス許可を保持することを指定します。

• CREATE OR REPLACE TASK

• CREATE TASK ... CLONE

このパラメーターは、 OWNERSHIP を 除く すべての許可を既存のタスクから新しいタスクにコピーします。デフォルトでは、 CREATE TASK コマンドを実行するロールが新しいタスクを所有します。

ノート：

• CREATE TASK ステートメントが複数のタスク（例： create or replace task t1 clone t2;）を参照している場合、 COPY GRANTS 句は置換されるタスクを優先します。

• 置換タスクの SHOW GRANTS 出力には、コピーされた権限の被付与者が、 CREATE TASK ステートメントを実行したロールとして、ステートメントが実行されたときの現在のタイムスタンプとともにリストされます。

• 許可をコピーする操作は、 CREATE TASK コマンドで（つまり、同じトランザクション内で）アトミックに発生します。

注釈

このパラメーターは現在サポートされていません。

COMMENT = '文字列リテラル'

タスクのコメントを指定します。

デフォルト：値なし

AFTER 文字列

現在のタスクの先行タスクを指定します。先行タスクの実行が正常に終了すると、このタスクがトリガーされます（短時間のラグの後）。

このパラメーターにより、タスクの単純なツリーを定義できます。つまり、依存関係によって編成された一連のタスク。このコンテキストでは、 ツリー は、スケジュールされたルートタスクで始まり、依存関係によって互いにリンクされている一連のタスクです。

注釈

• ツリーのルートタスクにはが定義されている必要があります。ツリー内の他の各タスクには、それらを相互にリンクするための定義済みの先行タスク（つまり、 AFTER パラメーターを使用して指定されたタスク）があります。

• タスクは単一の先行タスクに制限されています。ただし、タスクには最大100 子 タスク（つまり、タスクを先行タスクとして識別する他のタスク）を含めることができます。さらに、タスクの単純なツリーは、再開（つまり「開始」状態）または一時停止のいずれかで、最大 合計 1000タスク（ルートタスクを含む）に制限されます。

  たとえば、タスクT2は、T1などの単一の先行タスクに制限されています。ただし、T1は、タスクT2、T3、T4などの先行タスクとして機能できます。

• 単純なツリーのすべてのタスクには同じタスク所有者が必要です（つまり、単一のロールにはツリー内のすべてのタスクに対する OWNERSHIP 権限が必要です）。

• 単純なツリーのすべてのタスクは、同じスキーマに存在する必要があります。

• タスクツリーのルートタスクは、ツリー内の 任意の タスクが再作成される（ CREATE OR REPLACE TASK 構文を使用）か、子タスクが追加される（ CREATE TASK ... AFTER を使用する）前に一時停止する必要があります）。

• ツリー内のタスクのいずれかがクローンされると、タスクをクローンするロールがデフォルトでクローンの所有者になります。

  • 元のタスクの所有者がクローンを作成すると、タスククローンはタスクと先行タスクの間のリンクを保持します。これは、同じ先行タスクが元のタスクとタスククローンの両方をトリガーすることを意味します。

  • 別のロールがクローンを作成する場合、タスククローンはスケジュールを持てますが、先行タスクは持てません。

• アカウントは現在、最大10000再開タスクに制限されています。

• 現在の制限：

  • Snowflakeは、定義されたスケジュールを持つタスクの最大1つのインスタンスが特定の時間に実行されることを保証します。ただし、定義済みの先行タスクを持つタスクに対して同じ保証を提供することはできません。

WHEN ブール式

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

現在、 SQL 式で評価のためにサポートされているのは以下の関数 のみ です。

SYSTEM$STREAM_HAS_DATA

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

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

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

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

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

使用上の注意

• このコマンドを実行するには、次の権限が必要です。

  • スキーマのCREATE TASK 。

  • タスク定義のウェアハウスの USAGE。

  タスクを実行するには、タスクの所有者（つまり、タスクに対する OWNERSHIP 権限を持つロール）がグローバル EXECUTE TASK 権限も合わせて持つ必要があります。ロールの EXECUTE TASK 権限を取り消すと、以降のすべてのタスクの実行はそのロールで開始できなくなります。

  タスク定義に含める 前 に、 SQL ステートメントを実行するか、ストアドプロシージャを呼び出すことをお勧めします。タスク所有者のロールとしてこの手順を完了し、そのロールが SQL によって参照される任意のオブジェクトに対して必要な権限すべてを持っていることを確認します。

• タスクを作成した後、タスク定義で指定されたパラメーターに基づいてタスクが実行される前に、 ALTER TASK ... RESUME を実行する 必要 があります。アカウントは現在、最大10000再開タスクに制限されていることに注意してください。

  さらに、タスクがクローンされると、クローンされたタスクの実行はデフォルトで一時停止されるため、同じコマンドを使用して明示的に有効にする必要があります。

• タスクは、タスクに対する OWNERSHIP 権限を持つロールを使用して実行されます。SQL タスクによって実行されるステートメントは、ロールに必要な権限があるSnowflakeオブジェクトでのみ動作できます。

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

• 単一のテーブルストリームから変更データを消費する複数のタスクは、異なるデルタを取得します。タスクが DML ステートメントを使用してストリーム内の変更データを消費すると、ストリームはオフセットを進めます。変更データは、次に消費するタスクで使用できなくなります。現在は、単一のタスクのみがストリームの変更データを消費することをお勧めします。同じテーブルに対して複数のストリームを作成し、異なるタスクで使用できます。

• CREATE OR REPLACE 構文を使用すると、既存のタスクが削除され、指定された定義を使用して再作成されます。タスクのいずれかの現在の実行（つまり、 TASK_HISTORY 出力で EXECUTING 状態の実行）が完了します。指定されたタスクの実行を中止するには、 SYSTEM$USER_TASK_CANCEL_ONGOING_EXECUTIONS 関数を実行します。

例

現在のタイムスタンプを、日曜日（米国/ロサンゼルスタイムゾーン）の9 AM から5 PM で終わる1時間ごとにテーブルに挿入するタスクを作成します。タスクは、タスクが実行されるセッションの TIMESTAMP_INPUT_FORMAT パラメーターを設定します。

CREATE TASK mytask_hour
  WAREHOUSE = mywh
  SCHEDULE = 'USING CRON 0 9-17 * * SUN America/Los_Angeles'
  TIMESTAMP_INPUT_FORMAT = 'YYYY-MM-DD HH24'
AS
INSERT INTO mytable(ts) VALUES(CURRENT_TIMESTAMP);

追加のタイミング例：

SCHEDULE 値	説明
* * * * * UTC	毎分。UTC タイムゾーン。
0 2 * * * UTC	毎晩2 AM。UTC タイムゾーン。
0 5,17 * * * UTC	毎日2回、5 AM と5 PM （時間の一番上）。UTC タイムゾーン。
30 2 L 6 * UTC	6月、月末の2：30 AM。UTC タイムゾーン。

5分ごとに現在のタイムスタンプをテーブルに挿入するタスクを作成します。

CREATE TASK mytask_minute
  WAREHOUSE = mywh
  SCHEDULE = '5 MINUTE'
AS
INSERT INTO mytable(ts) VALUES(CURRENT_TIMESTAMP);

5分ごとに、ストリームから INSERT 操作の変更追跡データをテーブルに挿入するタスクを作成します。タスクは SYSTEM$STREAM_HAS_DATA 関数を使用してストリームをポーリングし、変更データが存在するかどうかを判断し、結果が FALSE の場合、現在の実行をスキップします。

CREATE TASK mytask1
  WAREHOUSE = mywh
  SCHEDULE = '5 minute'
WHEN
  SYSTEM$STREAM_HAS_DATA('MYSTREAM')
AS
  INSERT INTO mytable1(id,name) SELECT id, name FROM mystream WHERE METADATA$ACTION = 'INSERT';

既存の mytask1 タスクを、正常に実行されたときに新しい mytask2 タスクをトリガーする先行タスクとして指定することにより、タスクの単純なツリーを作成します。新しいタスクは mytable テーブルをクエリし、クエリ結果を別のテーブルに挿入します。

CREATE TASK mytask2
  WAREHOUSE = mywh
  AFTER mytask1
AS
INSERT INTO mytable2(id,name) SELECT id, name FROM mytable1;

ストアドプロシージャを呼び出す my_copy_task という名前のタスクを作成して、1時間ごとに mytable テーブルから名前付き mystage ステージにデータをアンロードします（ COPY INTO <場所> を使用）。

-- Create a stored procedure that unloads data from a table
-- The COPY statement in the stored procedure unloads data to files in a path identified by epoch time (using the Date.now() method)
create or replace procedure my_unload_sp()
  returns string not null
  language javascript
  as
  $$
    var my_sql_command = ""
    var my_sql_command = my_sql_command.concat("copy into @mystage","/",Date.now(),"/"," from mytable overwrite=true;");
    var statement1 = snowflake.createStatement( {sqlText: my_sql_command} );
    var result_set1 = statement1.execute();
  return my_sql_command; // Statement returned for info/debug purposes
  $$;

-- Create a task that calls the stored procedure every hour
create task my_copy_task
  warehouse = mywh
  schedule = '60 minute'
as
  call my_unload_sp();