カテゴリ：: データパイプライン 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> }' ]
  [ ALLOW_OVERLAPPING_EXECUTION = TRUE | FALSE ]
  [ <session_parameter> = <value> [ , <session_parameter> = <value> ... ] ]
  [ USER_TASK_TIMEOUT_MS = <num> ]
  [ USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = <string> ]
  [ 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"）。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

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

SQL

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

注釈

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

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

WAREHOUSE = 文字列

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

次のコンピューティングモデルは、このタスクの実行にコンピューティングリソースを提供するために使用できます。

このパラメーターの値を指定して、このタスクの実行にユーザー管理のコンピューティングリソース（つまり、ウェアハウス）を提供します。
このタスクの実行にSnowflakeが管理するコンピューティングリソースを使用するには、このパラメーターを完全に省略します。サーバーレスコンピューティングモデルとも呼ばれるこれらのリソースは、各ワークロードの必要に応じて、Snowflakeにより自動でサイズ変更、およびスケールアップまたはスケールダウンされます。タスクにスケジュールが指定されると、Snowflakeはリソースサイズを調整して、指定された時間枠内にタスクの将来の実行を完了します。

タスクの初期ウェアハウスサイズを指定するには、 USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 文字列 パラメーターを設定します。

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か月ごと）。その後も同じスケジュールが維持されます。つまり、タスクは1月（10月の実行から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 には決して実行されません）。

注釈

サポートされる最大値は 11520 （8日間）です。 数 MINUTE の値がこれよりも大きいタスクは実行されません。

ALLOW_OVERLAPPING_EXECUTION = TRUE | FALSE

タスクツリーの複数のインスタンスを同時に実行できるようにするかどうかを指定します。

注釈

このパラメーターは、ルートタスクでのみ設定できます。この設定は、ツリー内のすべてのタスクに適用されます。

このパラメーターはスタンドアロンタスクに設定できますが、タスクの動作には影響しません。Snowflakeは、スタンドアロンタスクの1つのインスタンスのみが特定の時間に実行されていることを確認します。

TRUE はルートタスクの1つのインスタンスのみが特定の時間に実行されていることを確認します。次の実行スケジュールが開始する際に、ルートタスクがまだ実行されている場合、そのスケジュールされた時間はスキップされます。この保証は、子タスクには適用されません。子タスクの現在の実行がまだ動作している間にルートタスクの次のスケジュールが実行されると、タスクツリーの別のインスタンスが開始されます。
FALSE は特定のツリーの1つのインスタンスのみが一度に実行できるようにします。ルートタスクの次の実行は、ツリー内のすべての子タスクの実行が終了した後にのみスケジュールされます。これは、ツリー内のすべてのタスクを実行するために必要な累積時間がルートタスクの定義で設定された明示的なスケジュールされた時間を超える場合、タスクツリーの少なくとも1つの実行がスキップされることを意味します。

デフォルト: FALSE

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

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

USER_TASK_TIMEOUT_MS = 数値

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

注釈

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

値： 0 - 86400000 （1日）。

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

USER_TASK_MANAGED_INITIAL_WAREHOUSE_SIZE = 文字列

このタスクの実行にサーバーレスコンピューティングモデルを使用する場合にのみ適用されます。

Snowflakeが理想的なサイズを決定するためにタスク履歴を使用できるようになる前に、タスクの最初の実行にプロビジョニングするコンピューティングリソースのサイズを指定します。タスクが数回の実行を正常に完了すると、Snowflakeはこのパラメーター設定を無視します。

特定のタスクでタスク履歴が利用できない場合、コンピューティングリソースはこの初期サイズに戻ることに注意してください。

注釈

WAREHOUSE = 文字列 パラメーター値が指定されている場合は、このパラメーターを設定するとユーザーエラーが発生します。

サイズは、 SMALL、 MEDIUM、 LARGE など、ウェアハウスの作成時に使用可能なコンピューティングリソース（CREATE WAREHOUSE を使用）と同等です。パラメーターでサポートされる最大サイズは XXLARGE です。パラメーターを省略した場合、タスクの最初の実行はMサイズ（MEDIUM）のウェアハウスを使用して実行されます。

初期サイズは、タスクが作成された後、正常に1度実行される前であれば変更できます（ALTER TASK を使用）。このタスクの最初の実行を開始した後にパラメーターを変更しても、現在または将来のタスク実行のコンピューティングリソースには影響しません。

タスクを一時停止および再開しても、コンピューティングリソースのサイズ設定に使用されたタスク履歴は削除されないことに注意してください。タスク履歴は、タスクが再作成された場合にのみ削除されます（CREATE OR REPLACE TASK 構文を使用）。

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日あたりの消費量は、クラウドサービスの料金に累積されません。

使用上の注意¶

タスクのサーバーレスコンピューティングモデルは、プレビュー機能としてサポートされています。
コンピューティングリソースに対して仮想ウェアハウスに依存するタスクを作成する場合、このコマンドを実行するロールには、指定されたウェアハウスに対する USAGE 権限が必要です。
タスクは、タスクに対する OWNERSHIP 権限を持つロールを使用して実行されます。SQL タスクによって実行されるステートメントは、ロールに必要な権限があるSnowflakeオブジェクトでのみ動作します。

タスク定義に含める前に、 SQL ステートメントを実行するか、ストアドプロシージャを呼び出すことをお勧めします。タスク所有者のロールとしてこのステップを完了し、そのロールが SQL によって参照される任意のオブジェクトに対して必要な権限すべてを持っていることを確認します。
タスクを実行するには、タスクの所有者（つまり、タスクに対する OWNERSHIP 権限を持つロール）がグローバル EXECUTE TASK 権限を持つ必要があります。ロールに対する EXECUTE TASK 権限を取り消すと、そのロールでは以降のタスクの実行すべてが開始できなくなります。

さらに、タスクがコンピューティングリソースをサーバーレスコンピューティングモデルに依存している場合、タスクの所有者は EXECUTE MANAGED TASK グローバル権限を持っている必要があります。
タスクの個々の実行に対するコンピューティングリソースは、Snowflake（つまり、サーバーレスコンピューティングモデル）またはユーザー指定の仮想ウェアハウスのいずれかによって管理されます。サーバーレスコンピューティングモデルを使用するには、 CREATE TASK ステートメントの WAREHOUSE = 文字列 パラメーターを省略します。
- タスクのSnowflake管理リソースは、ウェアハウスサイズで XSMALL から XXLARGE に相当する範囲になります。この範囲にさらに大きなウェアハウスサイズを含める場合は、 Snowflakeサポートに連絡してサイズの拡大をリクエストしてください。
- サーバーレスモデルは、タスクツリー内の1つ以上のタスクに対して有効にできます。ツリー内にある個々のタスクの実行は、Snowflakeまたはユーザーが管理するコンピューティングリソースのいずれかに依存します。ツリー内のすべてのタスクに対してこのサーバーレスコンピューティングモデルを有効にする必要はありません。
タスクを作成した後、タスク定義で指定されたパラメーターに基づいてタスクが実行される前に、 ALTER TASK ... RESUME を実行する必要があります。アカウントは現在、最大10000再開タスクに制限されていることに注意してください。

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

デフォルトでは、トランザクションを明示的に開始せずに実行された 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時間ごとにテーブルに挿入するサーバーレスタスクを作成します。初期のウェアハウスサイズは XSMALL です。タスクは、タスクが実行されるセッションの TIMESTAMP_INPUT_FORMAT パラメーターを設定します。

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

前の例と同じですが、タスクはユーザー管理のウェアハウスに依存して、実行用のコンピューティングリソースを提供します。

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();