スケジュールされたクエリの概念

クエリ文字列 – これは、結果を事前計算して別の Timestream for LiveAnalytics テーブルに保存しているクエリです。Timestream for LiveAnalytics の SQL サーフェス領域全体を使用してスケジュールされたクエリを定義できます。これにより、共通のテーブル式、ネストされたクエリ、ウィンドウ関数、または Timestream for LiveAnalytics のクエリ言語でサポートされているあらゆる種類の集計関数とスカラー関数を使用して、クエリを柔軟に記述できます。

スケジュール式 – スケジュールされたクエリのインスタンスが実行されるタイミングを指定できます。式は、cron 式 (UTC 午前 8 時に毎日実行など) または rate 式 (10 分おきに実行など) を使用して指定できます。

ターゲット設定 – スケジュールされたクエリの結果を、保存される送信先テーブルにマッピングする方法を指定できます。

通知設定 – Timestream for LiveAnalytics は、スケジュール式に基づいてスケジュールされたクエリのインスタンスを自動的に実行します。該当するクエリが実行されるたびに、スケジュールされたクエリの作成時に設定した SNS トピックで通知が届きます。この通知は、インスタンスが正常に実行されたか、エラーが発生したかを示します。また、計測されたバイト数、ターゲットテーブルに書き込まれたデータ、次の呼び出し時間などの情報も提供します。

以下は、この通知メッセージの例です。

{
    "type":"AUTO_TRIGGER_SUCCESS",
    "arn":"arn:aws:timestream:us-east-1:123456789012:scheduled-query/ PT1mPerMinutePerRegionMeasureCount-9376096f7309",
    "nextInvocationEpochSecond":1637302500,
    "scheduledQueryRunSummary":
    {
        "invocationEpochSecond":1637302440,
        "triggerTimeMillis":1637302445697,
        "runStatus":"AUTO_TRIGGER_SUCCESS",
        "executionStats":
        {
            "executionTimeInMillis":21669,
            "dataWrites":36864,
            "bytesMetered":13547036820,
            "recordsIngested":1200,
            "queryResultRows":1200
        }
    }
}

この通知メッセージでは、bytesMetered はクエリがソーステーブルでスキャンしたバイト数で、dataWrites はターゲットテーブルに書き込まれたバイト数です。

エラーレポートの場所 – スケジュールされたクエリは非同期的に実行され、ターゲットテーブルにデータを保存します。インスタンスでエラーが発生した場合 (無効なデータを保存できなかった場合など)、エラーが発生したレコードは、スケジュールされたクエリの作成時に指定した場所にあるエラーレポートに書き込まれます。場所の S3 バケットとプレフィックスを指定します。Timestream for LiveAnalytics は、スケジュールされたクエリ名と呼び出し時間をこのプレフィックスに追加し、スケジュールされたクエリの特定のインスタンスに関連するエラーを特定するのに役立ちます。

タグ付け – スケジュールされたクエリに関連付けできるタグをオプションで指定できます。詳細については、「リソースへのタグとラベルの追加」を参照してください。

例

次の例では、スケジュールされたクエリを使用して単純な集計を計算します。

SELECT region, bin(time, 1m) as minute, 
    SUM(CASE WHEN measure_name = 'metrics' THEN 20 ELSE 5 END) as numDataPoints 
FROM raw_data.devops 
WHERE time BETWEEN @scheduled_runtime - 10m AND @scheduled_runtime + 1m 
GROUP BY bin(time, 1m), region

@scheduled_runtime parameter – この例では、特別な名前付きパラメータ @scheduled_runtime を受け入れるクエリがあります。これは、スケジュールされたクエリの特定のインスタンスを呼び出すときにサービスが設定する (タイムスタンプ型の) 特別なパラメータです。これにより、スケジュールされたクエリの特定のインスタンスがソーステーブル内のデータを分析する時間範囲を確定的に制御できます。@scheduled_runtime は、クエリ内で、タイムスタンプ型が求められるすべての場所において使用できます。

スケジュール式を設定する例: cron(0/5 * * * ? *) では、スケジュールされたクエリが毎時 0、5、10、15、20、25、30、35、40、45、50、55 分に実行されます。2021-12-01 00:05:00 にトリガーされるインスタンスの場合、@scheduled_runtime パラメータはこの値に初期化されるため、この時刻のインスタンスは 2021-11-30 23:55:00～2021-12-01 00:06:00 の範囲内のデータで動作します。

時間範囲が重複するインスタンス – この例が示すように、スケジュールされたクエリの後続インスタンス 2 つの時間範囲が重複する場合があります。要件、指定する時間の述語、スケジュール式に基づいてこれを制御できます。この場合、この重複により、これらの計算では到着がわずかに (この例では最大 10 分) 遅延したデータに基づいて集計を更新できます。2021-12-01 00:00:00 にトリガーされたクエリ実行は 2021-11-30 23:50:00～2021-12-30 00:01:00、2021-12-01 00:05:00 にトリガーされたクエリ実行は 2021-11-30 23:55:00～2021-12-01 00:06:00 の時間範囲をカバーします。

正確性を確保し、ターゲットテーブルに保存された集計がソーステーブルから計算された集計と一致するように、Timestream for LiveAnalytics では、2021–12–01 00:05:00 の計算は 2021–12–01 00:00:00 の計算が完了した後にのみ実行されます。後の計算は、新しい値が生成された場合は、過去にマテリアライズされた集計を更新できます。内部的には、Timestream for LiveAnalytics ではレコードバージョンが使用され、スケジュールされたクエリの後のインスタンスによって生成されたレコードに、より大きなバージョン番号が割り当てられます。したがって、2021–12–01 00:05:00 の呼び出しによって計算された集計は、より新しいデータがソーステーブルにあれば、2021–12–01 00:00:00 の呼び出しによって計算された集計を更新できます。

自動トリガーと手動トリガー – スケジュールされたクエリが作成された後、Timestream for LiveAnalytics は指定されたスケジュールに基づいてインスタンスを自動的に実行します。このような自動トリガーは、サービスによって完全に管理されます。

一方、場合によっては、スケジュールされたクエリの一部のインスタンスを手動で開始する必要があります。例えば、クエリ実行で特定のインスタンスが失敗した場合や、自動スケジュール実行後にソーステーブルで遅延到着データや更新があった場合や、自動クエリ実行でカバーされない時間範囲 (スケジュールされたクエリの作成前の時間範囲など) のターゲットテーブルを更新する場合です。

ExecuteScheduledQuery API を使用して、@scheduled_runtime パラメータに使用される値である InvocationTime パラメータを渡すことで、スケジュールされたクエリの特定のインスタンスを手動で開始できます。ExecuteScheduledQuery API を使用する際の重要な考慮事項を以下に示します。