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

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

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

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

filterIndex を使用してインデックス付きデータのみを返すには、クエリで指定したフィールドでインデックス付けされたロググループのみをスキャンするようクエリに強制します。クエリで指定された フィールドを含むログイベントを持たないロググループをスキップし、このフィールドインデックスのクエリで指定された値と一致するロググループのみをスキャンすることで、スキャンされたボリュームを減らします。filterIndex を使用して、フィールド名と、指定されたフィールドと値を含むインデックス付きデータのみをクエリするフィールド名と値を指定します。

OpenSearch SQL は、標準ログクラスのロググループのクエリに使用できます。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'

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

filterIndex

SELECT * FROM `filterIndex('region' = 'us-east-1')` WHERE status = 200 LIMIT 10;

クエリで指定したフィールドでインデックスが作成されたロググループのみをスキャンするようにクエリに強制することで、インデックスが作成されたデータのみを返します。

グループ化の条件

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 を指定する必要があります。

LIMIT

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 など) に対するアクセス、変更、分析などの操作を可能にします。

Window 関数

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 ステートメントで複数のロググループを指定できます。

複数のデータソースを選択する

SELECT ds1.field1, ds1.field2 from `dataSource(['DataSource1', 'DataSource2'])` as ds1 where ds1.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'

データソースクエリでサポートされている SQL

SQL でデータソースをクエリするためのユースケースをサポートするには、dataSource コマンドを使用できます。この構文を使用して、 FROM コマンドでデータソースを指定することで、データソースをクエリできます。最大 10 個のデータソースを指定できます。

[Syntax] (構文)

`dataSource(
    ['DataSource1', 'DataSource2', ...'DataSourcen']
)`

クエリの例 

SELECT DS1.Column1, DS1.Column2 from `dataSource(
    ['DataSource1', 'DataSource2']
)` as DS1 WHERE DS1.Column1 = 'ABC'

クエリスコープ

AWS CLI および API では、ロググループ、データソースとタイプ、フィールドインデックスを使用して、クエリするログを指定できます。

ロググループ

ロググループのソース選択は、検索する必要がある正確なロググループ (複数可) がわかっている場合に使用できます。

SELECT * FROM `logGroups(logGroupIdentifier: ['/aws/lambda/my-function'])`;

データソースとタイプ

お客様は、データソース名とデータソースタイプを使用してログをクエリできます。

データソースとタイプベースのソース選択は、クエリが必要な正確なデータソースがわかっている場合に使用できます。このクエリは、指定されたデータソースとタイプを含む 1 つ以上のロググループで実行されます。

SQL でデータソースをクエリするためのユースケースをサポートするには、dataSource コマンドを使用できます。この構文を使用して、FROM コマンドでデータソースを指定することで、データソースをクエリできます。最大 10 個のデータソースを指定できます。

構文:

`dataSource(
    ['DataSource1.Type1', 'DataSource2.Type2', ...'DataSourcen.Typen']
)`

クエリの例:

SELECT DS1.Column1, DS1.Column2 from `dataSource(
    ['DataSource1.Type1', 'DataSource2.Type2']
)` as DS1 WHERE DS1.Column1 = 'ABC'

データソースによるクエリの詳細については、「」を参照してくださいファセットを使用してログをグループ化および探索する。

組み合わされた例

お客様はバックティック内のすべてのソース選択演算子を任意の順序で指定でき、結果は適用されるすべての条件の共通部分に基づきます。

たとえば、/aws/lambda/my-function-1 には、さまざまなインデックスを含む複数のデータソースとタイプが含まれている場合があります。次のクエリが実行されると、返される結果にはソースイベントとタイプ DataSource1.Type1 のイベントのみが含まれ、'status' = 200 の基準に一致します。

SELECT * FROM `
   logGroups(logGroupIdentifier: ['/aws/lambda/my-function'])
   filterIndex('status' = 200)
   dataSource(['DataSource1.Type1'])
`;

フィールドインデックス

フィールドインデックスベースのソース選択は、フィルターがインデックス付きフィールドをターゲットにするときに、関連するロググループを自動的に識別し、スキャンボリュームとクエリランタイムを削減します。

filterIndex を使用してインデックス付きデータのみを返すには、クエリで指定したフィールドでインデックス付けされたロググループのみをスキャンするようクエリに強制します。このフィールドでインデックス付けされるこれらのロググループの場合、インデックス付けされたフィールドのクエリで指定されたフィールドを含む任意のログイベントを持たないロググループをスキップすることで、クエリがさらに最適化されます。さらに、このフィールドインデックスのクエリで指定された値に一致するこれらのロググループのログイベントのみをスキャンしようとすることで、スキャンされるボリュームが減少します。フィールドインデックスとその作成方法の詳細については、「Create field indexes to improve query performance and reduce scan volume」を参照してください。

SQL では、filterIndex を使用して、インデックスとして扱うキーと値のペアを指定します。構文は次のとおりです。

SELECT * FROM `filterIndex('region' = 'us-east-1')`;

次のとおりです。

  1. filterIndex(...) は、キー値をフィールドインデックスとして扱います。各キーと値のペアはカンマで区切られます (以下の例)

  2. 「region」 =「us-east-1」は、適用する実際の条件を指定します。

    1. 注: = の代わりに、顧客は IN を使用して複数の値を指定できます (以下の例を参照)

複数の filterIndex を使用すると、「AND」を使用して条件が結合されます。この例では、us-east-1 または us-west-2 の status=200 と region に一致するログがクエリされます。

SELECT * FROM `filterIndex('status' = 200, 'region' IN ['us-east-1', 'us-west-2'])`;

制限事項

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

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

  • データソースクエリで JOIN またはサブクエリを使用することはできません。

  • ネストされたサブクエリは 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;