カテゴリ:: Information Schema、テーブル関数

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 } ] )

Copy

引数¶

すべての引数はオプションです。

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	タスクのステータス： `SCHEDULED`: 実行予定。 `EXECUTING`: 現在実行中。 `SUCCEEDED`: 実行成功。 `FAILED`: 実行失敗。 FAILED_AND_AUTO_SUSPENDED: タスクは失敗し、自動的に中断された。 `CANCELLED`: 実行中止。 `SKIPPED` は、タスクの実行が開始されたが、タスク定義のオプションの `WHEN` パラメーターが FALSE 値を返したことを示します。したがって、実行はウェアハウスを再開せず（タスクが顧客管理のコンピューティングリソースを使用する場合）、タスク定義の SQL コードを実行しませんでした。
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	正規化された SQL テキストに基づいて計算されたハッシュ値。 1
QUERY_HASH_VERSION	NUMBER	`QUERY_HASH` を計算するために使用されるロジックのバージョン。 1
QUERY_PARAMETERIZED_HASH	TEXT	パラメーター化されたクエリに基づいて計算されたハッシュ値。 1
QUERY_PARAMETERIZED_HASH_VERSION	NUMBER	`QUERY_PARAMETERIZED_HASH` を計算するために使用されるロジックのバージョン。 1

1(1,2,3,4): この列は、 2023_06動作変更バンドルが有効になっている場合にのみ表示されます。この列は、クエリハッシュ機能の一部です。

例¶

アカウントで、最新のタスク実行（完了、実行中、または将来のスケジュール）100個のを取得します。関数によって返される行の最大数は、デフォルトで100に制限されていることに注意してください。返される行数を変更するには、 RESULT_LIMIT 引数の値を変更します。

select *
  from table(information_schema.task_history())
  order by scheduled_time;

Copy

アカウントにある、過去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')));

Copy

過去1時間以内にスケジュールされた、指定されたタスクの最新の実行（完了、実行中、または将来のスケジュール）10個を取得します。

select *
  from table(information_schema.task_history(
    scheduled_time_range_start=>dateadd('hour',-1,current_timestamp()),
    result_limit => 10,
    task_name=>'MYTASK'));
Copy
注釈

完了または実行中のタスクのみを取得するには、 WHERE query_id IS NOT NULL を使用してクエリをフィルターします。 RESULT_LIMIT が返される結果を既に減らした後にこのフィルターが適用されるため、1つのタスクがスケジュールされていてもまだ開始されていない場合、クエリは9つのタスクを返す可能性があります。