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 和 CloudWatch。 Metrics Insights

支援的 SQL 命令

注意

在範例查詢欄中，根據您查詢的資料來源<logGroup>，視需要取代 。

命令或函數 查詢範例 Description

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;

僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。

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`

根據常見欄位聯結兩個資料表的結果。必須指定內部 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`

對多個資料列執行計算以產生單一摘要值的內建函數。例如，SUM、COUNT、AVG、MAX 和 MIN。

JSON 函數

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

用於在 SQL 查詢中剖析、擷取、修改和查詢 JSON 格式資料的內建函數 （例如，from_json、to_json、get_json_object、json_tuple)，允許在資料集中操作 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 陳述式中指定多個日誌群組

選取多個資料來源

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 個日誌群組。若要參考監控帳戶中的日誌群組，請使用 ARNs 而非LogGroup名稱。

查詢範例：

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

查詢 CloudWatch Logs 時，不支援在FROM陳述式之後涉及多個日誌群組的下列語法。

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

資料來源查詢支援的 SQL

若要支援在 SQL 中查詢資料來源的使用案例，您可以使用 dataSource 命令。使用此語法，您可以在 FROM命令中指定資料來源，以查詢資料來源。您最多可以指定 10 個資料來源。

語法

`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'])`;

資料來源和類型

客戶可以使用資料來源名稱和資料來源類型來查詢其日誌。

當客戶知道需要查詢哪些確切資料來源時，可以使用資料來源和類型型來源選擇。此查詢會透過一或多個包含指定資料來源和類型的日誌群組執行。

若要支援在 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 使用 僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。對於在此欄位上編製索引的這些日誌群組，它會略過沒有包含索引欄位查詢中指定欄位之任何日誌事件的日誌群組，以進一步最佳化查詢。它透過嘗試僅掃描這些日誌群組中符合此欄位索引查詢中指定值的日誌事件，進一步減少掃描的磁碟區。如需欄位索引及其建立方式的詳細資訊，請參閱建立欄位索引以改善查詢效能並降低掃描磁碟區。

在 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 中的日誌比對狀態=200 和區域。

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

限制

當您使用 OpenSearch SQL 在 CloudWatch Logs Insights 中查詢時，適用下列限制。

  • 您只能在 SELECT 陳述式中包含一個 JOIN。

  • 您無法搭配資料來源查詢使用 JOIN 或子查詢。

  • 僅支援一個層級的巢狀子查詢。

  • 不支援以分號 (；) 分隔的多個陳述式查詢。

  • 不支援包含相同但僅在 欄位名稱 （例如 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

  • 函數和表達式必須在欄位名稱上操作，並成為 SELECT 陳述式的一部分，其中包含 FROM 子句中指定的日誌群組。

    例如，不支援此查詢：

    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;