OpenSearch 構造化クエリ言語 (SQL) - Amazon CloudWatch Logs
サポートされている SQL コマンドmulti-log-group クエリでサポートされている SQL制限事項

OpenSearch 構造化クエリ言語 (SQL)

このセクションでは、OpenSearch SQL を使用した CloudWatch Logs のクエリの基本的な概要を示します。リレーショナルデータベースの使用に慣れている場合は、使い慣れたオプションを提供します。OpenSearch SQL は SQL 機能のサブセットを提供するため、アドホッククエリやデータ分析タスクの実行に適しています。OpenSearch SQL では、SELECT、FROM、WHERE、GROUP BY、HAVING、その他のさまざまな SQL コマンドや関数などのコマンドを使用できます。ロググループ間で JOINs を実行し、サブクエリを使用してロググループ間でデータを関連付け、一連の豊富な JSON、算術、文字列、条件付きなどの SQL 関数を使用してログとセキュリティデータに対する強力な分析を実行できます。

OpenSearch SQL は、標準ログクラスのロググループのクエリにのみ使用できます。

注記

次の表は、CloudWatch Logs でサポートされている SQL コマンドと関数の一覧です。構文を含むすべての OpenSearch SQL コマンドの詳細については、「OpenSearch Service デベロッパーガイド」の「サポートされている SQL コマンド」を参照してください。

使用できる他のクエリ言語については、「CloudWatch Logs Insights」、「OpenSearch Service PPL」、「CloudWatchMetrics Insights」を参照してください。

サポートされている SQL コマンド

注記

クエリの例の列では、クエリするデータソースに応じて、<logGroup> を適宜置き換えます。

コマンドまたは関数 サンプルクエリ 説明

SELECT

SELECT `@message`, Operation FROM `LogGroupA`

射影された値を表示します。

FROM

SELECT `@message`, Operation FROM `LogGroupA`

データを取得するソーステーブル (複数可) またはビュー (複数可) を指定する組み込み句。さまざまなタイプの結合とサブクエリをサポートします。

WHERE

SELECT * FROM `LogGroupA` WHERE Operation = 'x'

指定されたフィールド基準に基づいてログイベントをフィルタリングします。

GROUP BY

SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream`

グループはカテゴリに基づいてイベントをログに記録し、統計に基づいて平均を見つけます。

HAVING

SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream` HAVING log_count > 100

グループ化条件に基づいて結果をフィルタリングします。

ORDER BY

SELECT * FROM `LogGroupA` ORDER BY `@timestamp` DESC

ORDER BY 句のフィールドに基づいて結果が並べ替えられます。昇順または降順のいずれかで並べ替えることができます。

JOIN

SELECT A.`@message`, B.`@timestamp`FROM `LogGroupA` as A INNER JOIN `LogGroupB` as B ON A.`requestId` = B.`requestId`

共通フィールドに基づいて 2 つのテーブルの結果を結合します。Inner JOIN または Left Outer Join を指定する必要があります。

制限

Select * from `LogGroupA` limit 10

表示されるクエリ結果を最初の N 行に制限します。

文字列関数

SELECT upper(Operation) , lower(Operation), Operation FROM `LogGroupA`

SQL クエリ内の文字列およびテキストデータを操作および変換できる SQL の組み込み関数。例えば、大文字と小文字の変換、文字列の組み合わせ、パーツの抽出、テキストのクリーニングなどです。

日付関数

SELECT current_date() as today, date_add(current_date(), 30) as thirty_days_later, last_day(current_date()) as month_end FROM `LogGroupA`

SQL クエリで日付とタイムスタンプデータを処理および変換するための組み込み関数。例えば、date_add、date_format、datediff、current_date などです。

条件関数

SELECT Operation, IF(Error > 0, 'High', 'Low') as error_category FROM `LogGroupA`;

指定された条件に基づいてアクションを実行するか、式を条件付きで評価する組み込み関数。例えば、CASE と IF などです。

集計関数

SELECT AVG(bytes) as bytesWritten FROM `LogGroupA`

複数の行で計算を実行して 1 つの要約値を生成する組み込み関数。例えば、SUM、COUNT、AVG、MAX、MIN などです。

JSON 関数

SELECT get_json_object(json_column, '$.name') as name FROM `LogGroupA`

SQL クエリ (from_json、to_json、get_json_object、json_tuple など) 内の JSON 形式のデータを解析、抽出、変更、クエリするための組み込み関数。データセット内の JSON 構造を操作できます。

配列関数

SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;

SQL クエリで配列タイプの列を操作するための組み込み関数。配列データ (サイズ、展開、array_contains など) に対するアクセス、変更、分析などの操作を可能にします。

ウィンドウ関数

SELECT field1, field2, RANK() OVER (ORDER BY field2 DESC) as field2Rank FROM `LogGroupA`;

現在の行 (ウィンドウ) に関連する指定された行セットで計算を実行する組み込み関数。ランキング、合計実行、移動平均などの操作を有効にします。例えば、ROW_NUMBER、RANK、LAG、LEAD などです。

変換関数

SELECT CAST('123' AS INT) as converted_number, CAST(123 AS STRING) as converted_string FROM `LogGroupA`

SQL クエリ内でデータをあるタイプから別のタイプに変換するための組み込み関数。データ型変換と形式変換を可能にします。例えば、CAST、TO_DATE、TO_TIMESTAMP、BINARY などです。

述語関数

SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;

条件を評価し、指定された条件またはパターンに基づいてブール値 (true/false) を返す組み込み関数。例えば、IN、LIKE、BETWEEN、IS NULL、EXISTS などです。

複数のロググループを選択する

SELECT lg1.field1, lg1.field2 from `logGroups( logGroupIdentifier: ['LogGroup1', 'LogGroup2'])` as lg1 where lg1.field3= "Success"

SELECT ステートメントで複数のロググループを指定できます。

multi-log-group クエリでサポートされている SQL

SQL で複数のロググループをクエリするためのユースケースをサポートするには、logGroups コマンドを使用できます。この構文を使用し、FROM コマンドでそれらを指定することで複数のロググループをクエリできます。

構文:

`logGroups(
    logGroupIdentifier: ['LogGroup1','LogGroup2', ...'LogGroupn']
)

この構文では、logGroupIdentifier パラメータに最大 50 個のロググループを指定できます。モニタリングアカウントのロググループを参照するには、LogGroup の名前の代わりに ARN を使用します。

クエリの例:

SELECT LG1.Column1, LG1.Column2 from `logGroups(
    logGroupIdentifier: ['LogGroup1', 'LogGroup2']
)` as LG1 WHERE LG1.Column1 = 'ABC'

FROM ステートメントの後に複数のロググループを含む次の構文は、CloudWatch Logs のクエリではサポートされていません。

SELECT Column1, Column2 FROM 'LogGroup1', 'LogGroup2', ...'LogGroupn'
WHERE Column1 = 'ABC'

制限事項

OpenSearch SQL を使用して CloudWatch Logs Insights でクエリを実行する場合、次の制限が適用されます。

  • SELECT ステートメントに含めることができる JOIN は 1 つだけです。

  • ネストされたサブクエリは 1 つのレベルのみサポートされます。

  • セミコロン (;) で区切られた複数のステートメントのクエリはサポートされていません。

  • フィールド名が同一であるが、大文字や小文字のみが異なる (field1 および FIELD1 など) クエリはサポートされていません。

    例えば、次のクエリはサポートされません。

    Select AWSAccountId, AwsAccountId from LogGroup

    ただし、このフィールド名 (@logStream) は両方のロググループで同一であるため、次のクエリがサポートされています。

    Select a.`@logStream`, b.`@logStream` from Table A INNER Join Table B on a.id = b.id

  • 関数と式はフィールド名に対して操作し、FROM 句で指定されたロググループを持つ SELECT ステートメントの一部である必要があります。

    例として、次のクエリはサポートされていません。

    SELECT cos(10) FROM LogGroup

    このクエリはサポートされています。

    SELECT cos(field1) FROM LogGroup

  • SQL コマンドまたは PPL コマンドを使用する場合は、特定のフィールドをバッククオートで囲んでクエリを正常に実行します。特殊文字 (アルファベットや数字でないもの) を含むフィールドにはバッククオートが必要です。例えば、@message、Operation.Export、Test::Field をバッククォートで囲みます。フィールド名がアルファベットのみの場合はバッククオートで囲む必要はありません。

    シンプルなフィールドを含むクエリの例:

    SELECT SessionToken, Operation, StartTime  FROM `LogGroup-A`
LIMIT 1000;

    バッククオートが付け足された類似のクエリ:

    SELECT `@SessionToken`, `@Operation`, `@StartTime`  FROM `LogGroup-A` LIMIT 1000;