本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# OpenSearch 管道處理語言 (PPL)
<a name="CWL_AnalyzeLogData_PPL"></a>

本節包含使用 OpenSearch PPL 查詢 CloudWatch Logs 的基本簡介。透過 PPL，您可以使用管道互連命令擷取、查詢和分析資料，讓您更輕鬆地了解和編寫複雜的查詢。其語法是以 Unix 管道為基礎，並啟用命令鏈結來轉換和處理資料。使用 PPL，您可以篩選和彙總資料，並使用一組豐富的數學、字串、日期、條件式和其他函數進行分析。

在 PPL 查詢`SOURCE`中包含 是指定日誌群組欄位索引的實用方式，以及當您使用 AWS CLI 或 API 建立查詢時要包含在查詢中的資料來源。`SOURCE` 命令僅支援 AWS CLI 和 API，不支援 CloudWatch 主控台。當您使用 CloudWatch 主控台啟動查詢時，您可以使用主控台界面來指定日誌群組和資料來源名稱和類型。

`aws:fieldIndex` 使用 僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。系統會根據`filterIndex`命令中指定的欄位，自動選取相關的日誌群組。這可藉由略過沒有任何包含查詢中指定欄位之日誌事件的日誌群組，以及僅掃描符合此欄位索引查詢中指定值的日誌群組，來減少掃描的磁碟區。使用 `aws:fieldIndex`指定欄位名稱，以及來源命令中的欄位名稱和值，以僅查詢包含指定欄位和值的索引資料。如需詳細資訊，請參閱[建立欄位索引以改善查詢效能並減少掃描磁碟區](CloudWatchLogs-Field-Indexing.md) 

您可以使用 OpenSearch PPL 來查詢標準日誌類別中的日誌群組。

**注意**  
如需 CloudWatch Logs 中支援的所有 OpenSearch PPL 查詢命令的相關資訊，以及語法和限制的詳細資訊，請參閱 OpenSearch Service 開發人員指南中的[支援 PPL 命令](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-ppl.html)。  
 如需有關您可以使用之其他查詢語言的資訊，請參閱 [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)、[OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html) 和 [CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)


| 命令或函數 | 查詢範例 | Description | 
| --- | --- | --- | 
|  `fields` |  `fields field1, field2`  |  顯示一組需要投影的欄位。  | 
|  `join` |  `LEFT JOIN left=l, right=r on l.id = r.id `join_right_lg` \| fields l.field_1, r.field_2`  |  將兩個資料集聯結在一起。  | 
|  `where` |  `where field1="success" \| where field2 != "i-023fe0a90929d8822" \| fields field3, field4, field5,field6 \| head 1000`  |  根據您指定的條件篩選資料。  | 
|  `aws:fieldIndex` |  `source = [`aws:fieldIndex`="region", `region` = "us-west-2"] \| where status = 200 \| head 10`  |  僅傳回索引資料，方法是強制查詢僅掃描您在查詢中指定的欄位上編製索引的日誌群組。  | 
|  `stats` |  `stats count(), count(field1), min(field1), max(field1), avg(field1) by field2 \| head 1000`  |  執行彙總和計算  | 
|  `parse` |  `parse field1 ".*/(?<field2>[^/]+$)" \| where field2 = "requestId" \| fields field1, field2 \| head 1000`  |  從字串擷取規則表達式 (regex) 模式，並顯示擷取的模式。擷取的模式可以進一步用來建立新的欄位或篩選資料。  | 
|  `sort` |  `stats count(), count(field1), min(field1) as field1Alias, max(`field1`), avg(`field1`) by field2 \| sort -field1Alias \| head 1000`  |  依欄位名稱排序顯示的結果。使用 sort -FieldName 以遞減順序排序。  | 
|  `eval` |  `eval field2 = field1 * 2 \| fields field1, field2 \| head 20`  |  修改或處理欄位的值，並將其存放在不同的欄位中。這有助於以數學方式修改資料欄、將字串函數套用至資料欄，或將日期函數套用至資料欄。  | 
|  `rename` |  `rename field2 as field1 \| fields field1;`  |  重新命名搜尋結果中的一個或多個欄位。  | 
|  `head` |  `fields `@message` \| head 20`  |  將顯示的查詢結果限制為前 N 列。  | 
|  `top` |  `top 2 field1 by field2`  |  尋找欄位最常見的值。  | 
|  `dedup` |  `dedup field1 \| fields field1, field2, field3`  |  根據您指定的欄位移除重複的項目。  | 
|  `rare` |  `rare field1 by field2`  |  尋找欄位清單中所有欄位頻率最低的值。  | 
|  `subquery` |  `where field_1 IN [ search source= `subquery_lg` \| fields field_2 ] \| fields id, field_1 `  |  在您的 PPL 陳述式中執行複雜的巢狀查詢。  | 
|  `trendline` |  `trendline sma(2, field1) as field1Alias`  |  計算欄位的移動平均值。  | 
|  `eventStats` |  `eventstats sum(field1) by field2`  |  使用計算的摘要統計資料來豐富您的事件資料。它會分析事件中的指定欄位、運算各種統計指標，然後將這些結果做為新欄位附加到每個原始事件。  | 
|  `expand` |  `eval tags_array_string = json_extract(`@message`, '$.tags')\| eval tags_array = json_array(json_extract(tags_string, '$[0]'), json_extract(tags_string, '$[1]'))\| expand tags_array as color_tags`  |  將包含多個值的欄位細分為不同的資料列，為指定欄位中的每個值建立新的資料列。  | 
|  `fillnull` |  `fields `@timestamp`, error_code, status_code \| fillnull using status_code = "UNKNOWN", error_code = "UNKNOWN"`  |  使用您提供的值填入 null 欄位。它可用於一個或多個欄位。  | 
|  `flatten` |  `eval metadata_struct = json_object('size', json_extract(metadata_string, '$.size'), 'color', json_extract(metadata_string, '$.color')) \| flatten metadata_struct as (meta_size, meta_color) `  |  扁平化欄位。欄位必須屬於此類型： `struct<?,?>`或 `array<struct<?,?>>`。  | 
|  `cidrmatch` |  `where cidrmatch(ip, '2003:db8::/32') \| fields ip `  |  檢查指定的 IP 地址是否在指定的 CIDR 範圍內。 | 
|  `fieldsummary` |  `where field1 != 200 \| fieldsummary includefields= field1 nulls=true`  |  計算每個欄位的基本統計資料 （計數、相異計數、最小值、最大值、平均值、標準差和平均值）。  | 
|  `grok` |  `grok email '.+@%{HOSTNAME:host}' \| fields email, host`  |  剖析具有 grok 模式的文字欄位，並將結果附加到搜尋結果。  | 
|  字串函數 |  `eval field1Len = LENGTH(field1) \| fields field1Len`  |  PPL 中的內建函數，可以操作和轉換 PPL 查詢中的字串和文字資料。例如，轉換案例、合併字串、擷取部分和清除文字。  | 
|  日期時間函數 |  `eval newDate = ADDDATE(DATE('2020-08-26'), 1) \| fields newDate `  |  用於處理和轉換 PPL 查詢中日期和時間戳記資料的內建函數。例如，date\_add、date\_format、datediff、date-sub、timestampadd、timestampdiff、current\_timezone、utc\_timestamp 和 current\_date。  | 
|  條件函數 |  `eval field2 = isnull(field1) \| fields field2, field1, field3`  |  檢查特定欄位條件並依條件評估表達式的內建函數。例如，如果 field1 為 null，則傳回 field2。  | 
|  數學函數 |  `eval field2 = ACOS(field1) \| fields field1`  |  用於在 PPL 查詢中執行數學計算和轉換的內建函數。例如，abs （絕對值）、圓 （圓數）、sqrt （平方根）、pow （功率計算） 和 ceil （四捨五入至最接近的整數）。  | 
|  CryptoGraphic 函數 |  `eval crypto = MD5(field)\| head 1000`  |  計算指定欄位的雜湊  | 
|  JSON 函數 |  `eval valid_json = json('[1,2,3,{"f1":1,"f2":[5,6]},4]') \| fields valid_json`  |  處理 JSON 的內建函數，包括陣列、擷取和驗證。例如，json\_object、json\_array、to\_json\_string、json\_array\_length、json\_extract、json\_keys 和 json\_valid。  | 

## 查詢範圍
<a name="CWL_AnalyzeLogData_PPL-scope"></a>

當您使用 AWS CLI 或 API 建立查詢時，在查詢中包含 SOURCE 是指定要包含在查詢中的日誌群組的實用方式。SOURCE 命令僅支援 AWS CLI 和 API，不支援 CloudWatch 主控台。當您使用 CloudWatch 主控台啟動查詢時，您可以使用主控台界面來指定日誌群組和資料來源名稱和類型。

PPL 的來源命令現在支援多種指定方式：

1. 日誌群組

1. 欄位索引 - 新

1. 資料來源和類型 - 新

### 日誌群組
<a name="CWL_AnalyzeLogData_PPL-scope-loggroup"></a>

當客戶知道需要搜尋哪個確切的日誌群組 （日誌群組） 時，可以使用日誌群組來源選擇

```
source = [lg:`/aws/lambda/my-function`] | where status = 200 | head 10
```

### 欄位索引
<a name="CWL_AnalyzeLogData_PPL-scope-fieldindex"></a>

當篩選條件目標欄位已編製索引時，將結果限制為僅編製索引的資料，以欄位索引為基礎的來源選擇可減少查詢的資料量。系統會根據 `filterIndex`命令中指定的欄位，自動選取相關的日誌群組。如需欄位索引及其建立方式的詳細資訊，請參閱[建立欄位索引以改善查詢效能並降低掃描磁碟區](CloudWatchLogs-Field-Indexing.md)。

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

在 PPL 中， `aws:fieldIndex` 用於指定哪些索引鍵值對應視為索引。語法如下

```
source = [`aws:fieldIndex`="region", `region` = "us-west-2"] | where status = 200 | head 10
```

其中，

1. ``aws:fieldIndex`="region"` 將區域識別為欄位索引。

   1. 注意：而不是 = 客戶可以使用 IN 來指定多個索引 （範例如下）

1. ``region`="us-west-2"` 識別要套用的篩選條件

   1. 注意：而不是 = 客戶可以使用 IN 來指定多個值 （範例如下）

客戶可以指定多個 fieldIndexes，如下所示

```
source = [`aws:fieldIndex` IN ("status", "region"), `status` = 200, `region` IN ("us-west-2", "us-east-1")] | head 10
```

### 資料來源和類型
<a name="CWL_AnalyzeLogData_PPL-scope-datasource"></a>

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

```
source = [ds:`data_source.type`] | where status = 200 | head 10
```

#### 資料來源查詢支援的 PPL
<a name="CWL_AnalyzeLogData_PPL-scope-datasource-supported"></a>

若要支援在 PPL 中查詢資料來源的使用案例，您可以使用動態來源選取器子句。使用此語法，您可以在搜尋命令中指定資料來源，以查詢資料來源。您最多可以指定 10 個資料來源。

**語法**

```
source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`, ...ds:`DataSourcen.Typen`]
```

**查詢範例**

```
search source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`] | fields field1, field2
```

### 合併的範例
<a name="CWL_AnalyzeLogData_PPL-scope-combined"></a>

客戶可以按任何順序指定所有來源選取運算子，結果會是所有套用條件的交集。

例如，/aws/lambda/my-function-1 可能包含多個資料來源和類型，包括各種索引，當執行下列查詢時，傳回的結果只會有來源和類型 DataSource1.Type1 的事件，並符合 'status' = 200 的條件。

```
search source=[
    ds:`DataSource1.Type1`, 
    lg:`/aws/lambda/my-function-1`, 
    `aws:fieldIndex` IN ("status"), `status` = 200 
]
```

## 限制
<a name="CWL_AnalyzeLogData_PPL-restrictions"></a>

當您使用 OpenSearch PPL 在 CloudWatch Logs Insights 中查詢時，適用下列限制。
+ 您無法搭配資料來源查詢使用聯結或子查詢命令。