本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# OpenSearch 管道处理语言 (PPL)
本节包含使用 OpenSearch PPL 查询 CloudWatch 日志的基本介绍。借助 PPL，您可以使用管道连接的命令来检索、查询和分析数据，从而更轻松地理解和编写复杂的查询。其语法基于 Unix 管道，支持通过命令链实现数据的转换与处理。使用 PPL，您可以对数据进行筛选和聚合，并使用一组丰富的数学、字符串、日期、条件和其他函数进行分析。
使用 Amazon CLI 或 API 创建查询时，`SOURCE`在 PPL 查询中包含是指定要包含在查询中的日志组、字段索引和数据源的有用方法。只有 Amazon CLI 和 API 支持该`SOURCE`命令， CloudWatch 控制台不支持该命令。使用 CloudWatch控制台启动查询时，您可以使用控制台界面来指定日志组以及数据源的名称和类型。
使用 `aws:fieldIndex` 可以强制查询仅扫描在查询中指定的字段上编制索引的日志组，从而返回已编制索引的数据 根据`filterIndex`命令中指定的字段，将自动选择相关的日志组。这会跳过没有任何包含查询中指定字段的日志事件的日志组，而只扫描与该字段索引的查询中指定的值相匹配的日志组，从而减少扫描量。`aws:fieldIndex`用于在源命令中指定字段名称以及字段名称和值，以便仅查询包含指定字段和值的索引数据。有关更多信息，请参阅 [创建字段索引以提高查询性能并减少扫描量](CloudWatchLogs-Field-Indexing.md)。
您可以使用 OpenSearch PPL 查询标准日志类中的日志组。
**注意**
有关 CloudWatch 日志中支持的所有 OpenSearch PPL 查询命令的信息以及语法和限制的详细信息，请参阅《 OpenSearch 服务开发者指南》中的 “[支持的 PPL 命令](https://docs.amazonaws.cn/opensearch-service/latest/developerguide/supported-ppl.html)”。
有关您可以使用的其他查询语言的信息，请参阅 L [CloudWatch ogs Insights](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)、[Serv OpenSearch ice SQL](https://docs.amazonaws.cn/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html) 和 [CloudWatch Metrics Insights](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)
| 命令或函数 | 示例查询 | 说明 |
| --- | --- | --- |
| 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` | 根据指定的条件筛选数据。 |
| Amazon: 字段索引 | `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 ".*/(?[^/]+$)" \| where field2 = "requestId" \| fields field1, field2 \| head 1000` | 从字符串中提取正则表达式（regex）模式，并显示提取出的模式。提取出的模式可进一步用于创建新字段或筛选数据。 |
| 排序 | `stats count(), count(field1), min(field1) as field1Alias, max(`field1`), avg(`field1`) by field2 \| sort -field1Alias \| head 1000` | 按字段名称对显示的结果进行排序。使用 sor FieldName t-按降序排序。 |
| 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` | 使用计算得出的汇总统计数据丰富事件数据。它会分析您事件中的指定字段，计算各种统计指标，然后将这些结果作为新字段附加到每个原始事件上。 |
| 扩展 | `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>`。 |
| 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\$1add、date\$1format、datediff、date-sub、timestampadd、timestampdiff、current\$1timezone、utc\$1timestamp 和 current\$1date。 |
| 条件函数 | `eval field2 = isnull(field1) \| fields field2, field1, field3` | 内置函数，用于检查特定字段条件并有条件地计算表达式。例如，如果 field1 为空值，则返回 field2。 |
| 数学函数 | `eval field2 = ACOS(field1) \| fields field1` | 内置函数，用于在 PPL 查询中执行数学计算和转换。例如：abs（绝对值）、round（四舍五入）、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\$1object、json\$1array、to\$1json\$1string、json\$1array\$1length、json\$1extract、json\$1keys 和 json\$1valid。 |
## 查询范围
使用 Amazon CLI 或 API 创建查询时，在查询中包含 SOURCE 是指定要包含在查询中的日志组的有用方法。只有 Amazon CLI 和 API 支持 SOURCE 命令， CloudWatch控制台不支持。使用 CloudWatch 控制台启动查询时，您可以使用控制台界面来指定日志组以及数据源的名称和类型。
PPL 的 source 命令现在支持多种指定它们的方式：
1. 日志组
1. 字段索引-新增
1. 数据源和类型-新建
### 日志组
当客户知道需要搜索哪些确切的日志组时，可以使用日志组来源选择
```
source = [lg:`/aws/lambda/my-function`] | where status = 200 | head 10
```
### 字段索引
当筛选器针对已编制索引的字段时，基于字段索引的源选择将结果限制为仅包含索引的数据，从而减少了查询的数据量。根据`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 来指定多个值，而不是 =（以下示例）
客户可以指定多个字段索引，如下所示
```
source = [`aws:fieldIndex` IN ("status", "region"), `status` = 200, `region` IN ("us-west-2", "us-east-1")] | head 10
```
### 数据源和类型
当客户知道需要查询哪些确切的数据源时，可以使用基于数据源和类型的源选择。此查询是在一个或多个包含指定数据源和类型的日志组上执行的。
```
source = [ds:`data_source.type`] | where status = 200 | head 10
```
#### 支持用于数据源查询的 PPL
要支持在 PPL 中查询数据源的用例，您可以使用动态源选择器子句。使用此语法，您可以通过在搜索命令中指定数据源来查询数据源。您最多可以指定 10 个数据源。
**语法**
```
source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`, ...ds:`DataSourcen.Typen`]
```
**示例查询**
```
search source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`] | fields field1, field2
```
### 组合示例
客户可以按任意顺序指定所有来源选择运算符，结果将是所有应用条件的交集。
例如，/aws/lambda/my-function-1 可能包含多个数据源和类型，包括各种各样的索引，当运行以下查询时，返回的结果将只有源和 DataSource类型 1.Type1 的事件，并且符合 “状态” = 200 的标准。
```
search source=[
ds:`DataSource1.Type1`,
lg:`/aws/lambda/my-function-1`,
`aws:fieldIndex` IN ("status"), `status` = 200
]
```
## 限制
当您使用 OpenSearch PPL 在 Lo CloudWatch gs Insights 中进行查询时，以下限制适用。
+ 不能对数据源查询使用联接或子查询命令。