- カテゴリ:
TASK_HISTORY¶
このテーブル関数は、指定した日付範囲内の タスク の使用履歴をクエリするために使用できます。この関数は、Snowflakeアカウント全体または指定されたタスクの使用履歴を返します。
注釈
この関数は、過去7日間以内のタスクアクティビティ、または次の8日間以内にスケジュールされた次の実行を返します。
構文¶
TASK_HISTORY(
[ SCHEDULED_TIME_RANGE_START => <constant_expr> ]
[, SCHEDULED_TIME_RANGE_END => <constant_expr> ]
[, RESULT_LIMIT => <integer> ]
[, TASK_NAME => '<string>' ]
[, ERROR_ONLY => { TRUE | FALSE } ] )
引数¶
すべての引数はオプションです。
SCHEDULED_TIME_RANGE_START => constant_expr
、 .SCHEDULED_TIME_RANGE_END => constant_expr
タスクの実行がスケジュールされた過去7日以内の時間範囲( TIMESTAMP_LTZ 形式)。
SCHEDULED_TIME_RANGE_END
が指定されていない場合、関数は既に完了したタスク、現在実行中のタスク、または将来スケジュールされるタスクを返します。SCHEDULED_TIME_RANGE_END
が CURRENT_TIMESTAMP の場合、関数は既に完了したタスクまたは現在実行中のタスクを返します。現在時刻の直前に実行されるタスクは、スケジュール済みとして識別される場合があります。既に完了したタスクまたは現在実行中のタスクのみをクエリするには、フィルターに
WHERE query_id IS NOT NULL
を含めます。TASK_HISTORY 出力の QUERY_ID 列は、タスクの実行が開始されたときにのみ入力されます。
注釈
開始時刻または終了時刻が指定されていない場合、指定された RESULT_LIMIT 値までの最新のタスクが返されます。
時間範囲が過去7日以内に収まらない場合、エラーが返されます。
RESULT_LIMIT => integer
関数によって返される行の最大数を指定する数です。
一致する行の数がこの制限よりも大きい場合、指定された制限まで、最新のタイムスタンプを持つタスク実行が返されます。
範囲:
1
~10000
デフォルト:
100
。TASK_NAME => string
タスクを指定する、大文字と小文字を区別しない文字列。非修飾タスク名のみがサポートされています。指定されたタスクの実行のみが返されます。複数のタスクが同じ名前を持っている場合、関数はこれらの各タスクの履歴を返します。
ERROR_ONLY => TRUE | FALSE
TRUE に設定すると、この関数は失敗したかキャンセルされたタスク実行のみを返します。
使用上の注意¶
ACCOUNTADMIN ロール、タスク所有者(つまり、タスクに対する OWNERSHIP 権限を持つロール)、またはグローバル MONITOR EXECUTION 権限を持つロールの結果のみを返します。ロールが、 MONITOR EXECUTION 権限に加えて、タスクを保存するデータベースとスキーマに対する USAGE 権限を持つ場合以外は、出力の DATABASE_NAME および SCHEMA_NAME 値は NULL であることに注意してください。
この関数は、
RESULT_LIMIT
引数値に設定されている行数を返します。最大値は10,000行です。デフォルト値は100
です。この制限を回避するには、 TASK_HISTORY ビュー (Account Usage)を使用します。TASK_HISTORY 関数がクエリされると、そのタスク名、時間範囲、および結果制限引数が 最初 に適用され、指定されている場合はそれぞれ WHERE 句と LIMIT 句が続くことに注意してください。さらに、 TASK_HISTORY 関数は SCHEDULED_TIME の降順で記録を返します。完了した(つまり、 SUCCEEDED、 FAILED、または CANCELLED 状態の)タスクは、より早くスケジュールされる傾向があるため、通常、後で検索結果に表示された順に返されます。
実際には、アカウントで多数のタスクを実行している場合、特に RESULT_LIMIT 値が比較的低い場合、関数によって返される結果には、想定より少ない数の完了したタスクまたはスケジュールされたタスクのみが含まれる可能性があります。すでに実行されているタスクの履歴をクエリするには、
SCHEDULED_TIME_RANGE_START => constant_expr
および/またはSCHEDULED_TIME_RANGE_END => constant_expr
引数の組み合わせを使用することをSnowflakeはお勧めします。Information Schemaテーブル関数を呼び出す場合、セッションには使用中の INFORMATION_SCHEMA スキーマ または 完全修飾の関数名が必要です。詳細については、 Snowflake Information Schema をご参照ください。
この関数は、過去7日以内に実行されたすべての実行または次の8日以内にスケジュールされた実行を返すことができます。
出力¶
この関数は、次の列を返します。
列名 |
データ型 |
説明 |
---|---|---|
QUERY_ID |
TEXT |
タスクによって実行された SQL ステートメントのID です。ステートメントまたはストアドプロシージャの実行に関する追加の詳細は、 QUERY_HISTORY ビューと結合できます。 |
NAME |
TEXT |
タスクの名前。 |
DATABASE_NAME |
TEXT |
タスクを含むデータベースの名前です。 |
SCHEMA_NAME |
TEXT |
タスクを含むスキーマの名前。 |
QUERY_TEXT |
TEXT |
SQL ステートメントのテキスト。 |
CONDITION_TEXT |
TEXT |
実行するかどうかを決定するときにタスクが評価する WHEN 条件のテキスト。 |
STATE |
TEXT |
タスクのステータス:
|
ERROR_CODE |
NUMBER |
ステートメントがエラーを返した場合のエラーコードです。 |
ERROR_MESSAGE |
TEXT |
ステートメントがエラーを返した場合のエラーメッセージです。 |
SCHEDULED_TIME |
TIMESTAMP_LTZ |
タスクが実行を開始する/スケジュールされた時刻です。絶対精度を確保するために最善を尽くしますが、保証は、スケジュールされた時間の 前 にタスクが実行されないようにすることのみに限定されます。 |
INSTANCE_ID |
NUMBER |
タスクの内部/システム生成識別子。 |
QUERY_START_TIME |
TIMESTAMP_LTZ |
タスク定義内のクエリの実行が開始された時刻、または SCHEDULED_TIME が未来の場合、または現在スケジュールされている実行がまだ開始されていない場合は NULL。このタイムスタンプは、 QUERY_HISTORY によって返されるクエリの開始時間と一致します。 |
NEXT_SCHEDULED_TIME |
TIMESTAMP_LTZ |
SCHEDULED_TIME時に開始されたスタンドアロンタスクまたはDAGの現在の実行が時間内に完了すると仮定して、スタンドアロンタスクまたはルートタスク(タスクの DAG 内)が次に実行を開始するようにスケジュールされる時間。 |
COMPLETED_TIME |
TIMESTAMP_LTZ |
タスクが完了した時刻、または SCHEDULED_TIME が将来の場合、またはタスクがまだ実行中の場合は NULL になります。 |
ROOT_TASK_ID |
TEXT |
DAG内のルートタスクの一意の識別子。この ID は、同じタスクの SHOW TASKS 出力にある ID 列の値と一致します。 |
GRAPH_VERSION |
NUMBER |
実行された、または実行予定のDAGのバージョンを識別する整数。値の増分の増加は、DAG内のタスクに対する1つ以上の変更を表します。ルートタスクが( CREATE OR REPLACE TASK を使用して)再作成された場合、バージョン番号は1から再開します。 |
RUN_ID |
NUMBER |
DAG内のスタンドアロンタスクまたはルートタスクが本来実行を開始するようにスケジュールされている、またはされていた時間。形式はエポック時間(単位:ミリ秒)です。ROOT_TASK_ID値とRUN_ID値の組み合わせは、 DAG の特定の実行を識別します。 . 元の スケジュール時間とは、システムが同じタスクを再スケジュールして異なる時間に実行し、再試行またはロードのリバランスを行うまれなインスタンスを指します。その場合、 RUN_ID は元のスケジュールされた実行時間を示し、 SCHEDULED_TIME は再スケジュールされた実行時間を示します。 |
RETURN_VALUE |
TEXT |
DAG内の先行タスクに設定された値です。戻り値は、先行タスクで SYSTEM$SET_RETURN_VALUE 関数を呼び出すことにより、明示的に設定されます。 |
SCHEDULED_FROM |
TEXT |
タスク実行を求めたメカニズム: SCHEDULE は、タスク実行がタスク定義のスケジュールによって開始されたことを示します。EXECUTE TASK タスクの実行が、 EXECUTE TASK ステートメントの実行によって開始されたことを示します。DAGにある子タスクの実行の場合、列はルートタスクの実行と同じ値を返します。 |
ATTEMPT_NUMBER |
NUMBER |
このタスクの実行を試行した回数を表す整数。初期値は1。 |
CONFIG |
TEXT |
ルートタスクに設定されている場合はグラフレベルの構成を表示します。それ以外の場合は NULL を表示します。 |
QUERY_HASH |
TEXT |
|
QUERY_HASH_VERSION |
NUMBER |
|
QUERY_PARAMETERIZED_HASH |
TEXT |
|
QUERY_PARAMETERIZED_HASH_VERSION |
NUMBER |
|
例¶
アカウントで、最新のタスク実行(完了、実行中、または将来のスケジュール)100個のを取得します。関数によって返される行の最大数は、デフォルトで100に制限されていることに注意してください。返される行数を変更するには、 RESULT_LIMIT 引数の値を変更します。
select * from table(information_schema.task_history()) order by scheduled_time;
アカウントにある、過去7日以内に指定された30分単位のタスクの実行履歴を取得します。
select * from table(information_schema.task_history( scheduled_time_range_start=>to_timestamp_ltz('2018-11-9 12:00:00.000 -0700'), scheduled_time_range_end=>to_timestamp_ltz('2018-11-9 12:30:00.000 -0700')));
過去1時間以内にスケジュールされた、指定されたタスクの最新の実行(完了、実行中、または将来のスケジュール)10個を取得します。
select * from table(information_schema.task_history( scheduled_time_range_start=>dateadd('hour',-1,current_timestamp()), result_limit => 10, task_name=>'MYTASK'));注釈
完了または実行中のタスクのみを取得するには、
WHERE query_id IS NOT NULL
を使用してクエリをフィルターします。RESULT_LIMIT
が返される結果を既に減らした 後に このフィルターが適用されるため、1つのタスクがスケジュールされていてもまだ開始されていない場合、クエリは9つのタスクを返す可能性があります。