翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

スケジュールされたクエリの概念を理解する

スケジュールされたクエリを作成する前に、クエリの実行方法と結果の配信先に影響するこれらの主要な概念を理解してください。

IAM ロールの分離

スケジュールされたクエリには 2 つの異なる IAM ロールが必要です。1 つはクエリを実行するためのロールで、もう 1 つは Amazon S3 バケット、Amazon EventBridge イベントバス、ルックアップテーブルなどの送信先に結果を配信するためのロールです。この分離が存在する理由を理解すると、アクセス許可を正しく設定し、セキュリティと運用上の利点を活用できます。

2 ロールアーキテクチャは、データアクセスとデータ配信の責任を分けます。クエリ実行ロールはログデータにアクセスしてクエリを実行し、送信先配信ロールは選択した送信先に結果を書き込みます。この分離は最小特権の原則に従います。各ロールには、特定の関数に必要なアクセス許可のみがあります。

この分離は、オペレーションに実用的な利点をもたらします。セキュリティの観点から、結果の配信先を変更する必要がある場合は、クエリ実行のアクセス許可を変更せずに送信先配信ロールのみを変更します。コンプライアンスと監査のために、機密ログデータにアクセスするロールと外部システムに書き込むロールを明確に追跡できます。これにより、ログ分析インフラストラクチャがセキュリティのベストプラクティスに従っていることを簡単に実証できます。

クロスリージョンおよびクロスアカウントの使用

スケジュールされたクエリは、特定のリージョンで作成され、そのリージョンで実行されます。ただし、ロググループをクエリし、リージョンとアカウント間で結果を配信することはできます。1 つ以上の AWS アカウントをモニタリングアカウントとして設定し、複数のソースアカウントにリンクする必要があります。モニタリングアカウントは、ソース AWS アカウントから生成されたオブザーバビリティデータを表示して操作できる中央アカウントです。ソースアカウントは、そのアカウントに存在するリソースのオブザーバビリティデータを生成する個々の AWS アカウントです。ソースアカウントは、オブザーバビリティデータをモニターリングアカウントと共有します。そのため、すべてのリンクされたアカウントのロググループを使用して、モニタリングアカウントからスケジュールされたクエリを設定できます。

代替方法: CloudWatch Logs の一元管理を使用して、複数のアカウントとリージョンのログデータを一元的なモニタリングアカウントにレプリケートします。これにより、すべての一元化されたログにアクセスするスケジュールされたクエリを 1 つのリージョンに作成できるため、リージョン間のクエリを回避し、IAM アクセス許可の管理を簡素化できます。

スケジュール式とタイムゾーン処理

定義したスケジュールによって、クエリの実行日時と実行頻度が決まります。適切なスケジュール式を選択すると、結果を受け取るタイミングとクエリするデータ量に影響します。式タイプを理解すると、シンプルさと精度のどちらかを選択できます。

Cron 式はタイミングを正確に制御するため、正確な時間、曜日、または曜日を指定できます。特定の営業時間にクエリを実行したり、運用スケジュールに合わせる必要がある場合は、cron 式を使用します。コンソールでは、簡単なカレンダーオプションを使用してクエリをスケジュールすることもできます。

スケジュールされたクエリはすべて、ローカルのタイムゾーンや AWS リソースの場所に関係なく、UTC で実行されます。これは、営業時間や時間的制約のある分析のクエリをスケジュールするときに特に重要です。たとえば、米国東部標準時で事業を運営していて、米国東部標準時午前 9 時に日次レポートが必要な場合は、UTC オフセット (夏時間中は 14:00 UTC、それ以外の場合は 13:00 UTC) を考慮する必要があります。クエリが意図した時間に実行されるように、UTC を念頭に置いてスケジュール式を計画します。

クエリ言語の選択

スケジュールされたクエリは 3 つの異なるクエリ言語をサポートしており、クエリの記述方法とチームがクエリを簡単に維持できるかどうかの両方に影響します。適切な言語は、分析要件とチームの既存のスキルによって異なります。

主にログデータをフィルタリングおよび集計する場合、CloudWatch Logs Insights クエリ言語は最も単純な構文を提供します。複数のステップでデータを再形成または強化する必要がある複雑なデータ変換の場合、PPL のパイプラインアプローチにより、ロジックに従うのが容易になります。データベースオペレーションと同様の結合や複雑な集計を実行する必要がある場合、SQL はデータベース経験豊富なチームがすばやく採用できる使い慣れた構文を提供します。

送信先の選択とユースケース

クエリ結果を送信する場所によって、クエリ結果で何ができるかが決まります。この選択により、長期的な分析の構築、自動応答のトリガー、またはその両方を行うかどうかにかかわらず、ダウンストリームワークフロー全体が形成されます。各送信先タイプの長所を理解することは、ユースケースに適したアーキテクチャを設計するのに役立ちます。

Amazon S3 の送信先は、ストレージとバッチ処理用に最適化されています。クエリ結果を数か月または数年間保持したり、経時的な傾向を分析したり、データを分析プラットフォームにフィードしたりする必要がある場合、Amazon S3 は無制限の保持で費用対効果の高いストレージを提供します。EventBridge の送信先は、リアルタイムオートメーション用に最適化されています。クエリ結果がアラートの送信、ワークフローの開始、システムの更新などの即時アクションをトリガーする場合、EventBridge はアプリケーションが即座に応答できるイベントとして結果を提供します。デフォルトでは、すべてのクエリ完了イベントはイベントとしてデフォルトのイベントバスに自動的に送信され、ダウンストリーム処理システム、Lambda 関数、またはその他のイベント駆動型アーキテクチャとの統合が可能になります。結果は、クエリが正常に実行された場合にのみ送信先に発行されます。ルックアップテーブルの送信先は、参照データを最新の状態に保つように最適化されています。ルックアップテーブルの送信先は、指定されたルックアップテーブルにスケジュールされた各実行のクエリ結果を自動的に入力または更新するため、他のクエリは lookup コマンドを使用して最新のデータを参照できます。

クエリ結果の形式と構造

スケジュールされたクエリは JSON 形式で結果を提供しますが、送信先タイプごとに異なるペイロードを受け取ります。ルックアップテーブルの送信先の場合、クエリ結果はルックアップテーブルのコンテンツになり、各実行はそのコンテンツを置き換えます。詳細については、「スケジュールされたクエリのルックアップテーブルの送信先の設定」を参照してください。

Amazon S3 の送信先は、クエリの結果行を受け取ります。各オブジェクトには、結果セットの各行に 1 つのエントリを持つ JSON 配列が含まれ、各エントリはクエリの出力フィールド名を値にマッピングします。オブジェクトにはクエリメタデータやクエリ統計が含まれておらず、クエリがリクエストしても @ptr フィールドは省略されます。これは、そのフィールドがコンソールでのみ使用できるためです。

EventBridge の送信先は、クエリ統計を含むクエリメタデータを受信しますが、結果行は受信しません。完了したクエリの行を取得するには、イベントqueryIdから の値を使用して GetQueryResults を呼び出します。

次の例は、スケジュールされたクエリが完了したときに CloudWatch Logs が EventBridge に発行するイベントを示しています。

{
    "version": "0",
    "id": "be72061b-eca2-e068-a7e1-83e01d6fe807",
    "detail-type": "Scheduled Query Completed",
    "source": "aws.logs",
    "account": "123456789012",
    "time": "2025-11-18T11:31:48Z",
    "region": "us-east-1",
    "resources": [
        "arn:aws:logs:us-east-1:123456789012:scheduled-query:477b4380-b098-474e-9c5e-e10a8cc2e6e7"
    ],
    "detail": {
        "queryId": "2038fd57-ab4f-4018-bb2f-61d363f4a004",
        "queryString": "fields @timestamp, @message, @logStream\n| filter @message like /ERROR/\n| sort @timestamp desc\n| limit 10000",
        "logGroupIdentifiers": [
            "/aws/lambda/my-function"
        ],
        "status": "Complete",
        "startTime": 1763465460,
        "statistics": {
            "recordsMatched": 1842,
            "recordsScanned": 48325,
            "estimatedRecordsSkipped": 0,
            "bytesScanned": 12081250,
            "estimatedBytesSkipped": 0,
            "logGroupsScanned": 1,
            "resultCount": 1842
        }
    }
}

このクエリは集計されず、10,000 limit行よりも少ない行が返されたため、一致する 1,842 ログイベントはそれぞれ 1 つの出力行になり、 recordsMatched と resultCountは等しくなります。集計するクエリ、または結果セットが によって切り捨てられるクエリはlimit、 よりもresultCount低い を生成しますrecordsMatched。詳細については、「recordsScanned、recordsMatched、resultCount について」を参照してください。

主な要素は次のとおりです。

次の表に、 statistics オブジェクトの各フィールドを示します。これらのフィールドの API 定義については、QueryStatistics」を参照してください。

recordsScanned、recordsMatched、resultCount について

3 つのクエリ統計はさまざまなものをカウントし、それらを直接比較すると誤解を招く可能性があります。それぞれ異なるクエリ処理のステージを測定します。

各ステージはデータを絞り込みます。などのコマンドstatsは、多くのログイベントを 1 つの出力行に結合するため、 よりもはるかに小さくresultCountすることができますrecordsMatched。大きい recordsMatchedと小さい resultCount は、行が結果セットから欠落していることを意味するものではありません。

例 – 集計

次のクエリは、1 時間の 1 つのロググループの各ログストリームのエラーメッセージをカウントします。

filter @message like /ERROR/
| stats count(*) as errorCount by @logStream

クエリが 1,500,000 個のログイベントを読み取り、そのうち 24,318 個に が含まれERROR、一致するログイベントが 12 個のログストリームから取得された場合、クエリは次の統計情報で完了します。

"statistics": {
    "recordsMatched": 24318,
    "recordsScanned": 1500000,
    "estimatedRecordsSkipped": 0,
    "bytesScanned": 450000000,
    "estimatedBytesSkipped": 0,
    "logGroupsScanned": 1,
    "resultCount": 12
}

stats はログストリームごとに 1 行を生成するため、 resultCountは 12、 recordsMatched は 24,318 です。の 12 個の値errorCountの合計は 24,318 です。

例 – 集計後フィルター

次のクエリは、1,000 を超えるエラーを生成したログストリームのみを保持します。

filter @message like /ERROR/
| stats count(*) as errorCount by @logStream
| filter errorCount > 1000

最後のfilterコマンドはグループ化後に実行されるため、スキャンのログイベントではなく、結果セットから行が削除されます。12 個のログストリームのうち 3 個が 1,000 errorCountより大きい場合、 resultCountは 12 ではなく 3 になります。 recordsScannedと は変更bytesScannedされません。クエリはどちらの方法でも同じログデータを読み取ります。

例 – 制限

limit コマンドは、集約resultCountなしで を減らします。次のクエリは、最新のエラーメッセージ 100 件を返します。

filter @message like /ERROR/
| sort @timestamp desc
| limit 100

クエリが同じ 1,500,000 個のログイベントをスキャンし、同じ 24,318 個と一致する場合、 resultCountは 100 になります。これは、limit結果が 100 行に設定されているためです。コンソールでは、この関係は 24,318 件のレコードのうち 100 件が一致すると表示されます。

各統計は異なる質問に答えます。