# CloudWatch 搜索表达式语法
有效的搜索表达式具有以下格式。
```
SEARCH(' {Namespace, DimensionName1, DimensionName2, ...} SearchTerm', 'Statistic')
```
例如：
```
SEARCH('{AWS/EC2,InstanceId} MetricName="CPUUtilization"', 'Average')
```
+ 查询中单词 `SEARCH` 之后的第一部分（用大括号括起来）是要搜索的*指标架构*。指标架构包含指标命名空间以及一个或多个维度名称。在搜索查询中包含指标架构是可选的。如果指定，则指标架构必须包含命名空间，并且可以（可选）包含在该命名空间中有效的一个或多个维度名称。
除非命名空间或维度名称包含空格或非字母数字字符，否则不需要在指标架构中使用引号。在这种情况下，您必须用双引号将包含这些字符的名称引起来。
+ `SearchTerm` 也是可选的，但有效的搜索必须包含指标架构和/或 `SearchTerm`。`SearchTerm` 通常包含一个或多个账户 ID、指标名称或维度值。`SearchTerm` 可以通过部分匹配和精确匹配来包含要搜索的多个词语。它还可以包含布尔运算符。
在 `SearchTerm` 中使用账户 ID 仅适用于设置为 CloudWatch 跨账户可观测性监控账户的账户。`SearchTerm` 中账户 ID 的语法是 `:aws.AccountId = 444455556666`。您也可以使用 `'LOCAL'` 来指定监控账户本身：`:aws.AccountId = 'LOCAL'`
有关更多信息，请参阅 [CloudWatch 跨账户可观测性](CloudWatch-Unified-Cross-Account.md)。
`SearchTerm` 可以包含一个或多个指示符，例如 `MetricName=`（如本例中所示），但不需要使用指示符。
指标架构和 `SearchTerm` 必须一起包含在一对单引号中。
+ `Statistic` 是任何有效 CloudWatch 统计数据的名称。它必须用单引号引起来。有关更多信息，请参阅 [统计信息](cloudwatch_concepts.md#Statistic)。
上述示例在 `AWS/EC2` 命名空间中搜索任何具有 `InstanceId` 作为维度名称的指标。它会返回找到的所有 `CPUUtilization` 指标，图表显示 `Average` 统计数据。
搜索表达式只能找到在过去两周内报告了数据的指标。
**搜索表达式限制**
最大搜索表达式查询大小为 1024 个字符。一个图表上最多可以包含 100 个搜索表达式。一个图表可以显示多达 500 个时间序列。
## CloudWatch 搜索表达式：令牌化
当您指定 `SearchTerm` 时，搜索函数会搜索*令牌*，即 CloudWatch 自动根据完整的指标名称、维度名称、维度值和命名空间生成的子字符串。CloudWatch 生成的令牌在原始字符串中以驼峰式大小写区分。数字字符也可用作新令牌的开头，非字母数字字符用作分隔符，从而在非字母数字字符之前和之后创建令牌。
相同类型的令牌分隔符字符的连续字符串会生成一个令牌。
所有生成的令牌都是小写的。下表显示了一些生成的令牌示例。
| 原始字符串 | 生成的令牌 |
| --- | --- |
| CustomCount1 | `customcount1`, `custom`, `count`, `1` |
| SDBFailure | `sdbfailure`, `sdb`, `failure` |
| Project2-trial333 | `project2trial333`, `project`, `2`, `trial`, `333` |
## CloudWatch 搜索表达式：部分匹配项
当您指定 `SearchTerm` 时，搜索词也会被令牌化。CloudWatch 根据部分匹配项查找指标，部分匹配项是根据搜索词生成的单个令牌与根据指标名称、命名空间、维度名称或维度值生成的单个令牌的匹配项。
与单个令牌匹配的部分匹配搜索是不区分大小写的。例如，使用以下任一搜索词可能会返回 `CustomCount1` 指标：
+ `count`
+ `Count`
+ `COUNT`
但是，使用 `couNT` 作为搜索词不会找到 `couNT`，因为搜索词 `CustomCount1` 中的大写会被令牌化为 `cou` 和 `NT`。
搜索还可以匹配复合令牌，复合令牌是在原始名称中连续出现的多个令牌。为与复合令牌匹配，搜索是区分大小写的。例如，如果原始词是 `CustomCount1`，则 `CustomCount` 或 `Count1` 的搜索成功，但 `customcount` 或 `count1` 的搜索不成功。
## CloudWatch 搜索表达式：精确匹配项
您可以定义搜索，以便通过使用双引号将搜索词中需要精确匹配的部分引起来，仅查找搜索词的精确匹配项。这些双引号被括在将整个搜索词引起来的单引号中。例如，**SEARCH(' \$1MyNamespace\$1, "CustomCount1" ', 'Maximum')** 找到确切的字符串 `CustomCount1`（如果它在名为 `MyNamespace` 的命名空间中作为指标名称、维度名称或维度值存在）。但是，搜索 **SEARCH(' \$1MyNamespace\$1, "customcount1" ', 'Maximum')** 或 **SEARCH(' \$1MyNamespace\$1, "Custom" ', 'Maximum')** 找不到该字符串。
您可以在单个搜索表达式中组合部分匹配词和精确匹配词。例如，**SEARCH(' \$1AWS/NetworkELB, LoadBalancer\$1 "ConsumedLCUs" OR flow ', 'Maximum')** 会返回名为 `ConsumedLCUs` 的 Elastic Load Balancing 指标和包含令牌 `flow` 的所有 Elastic Load Balancing 指标或维度。
使用精确匹配也是查找具有特殊字符（例如非字母数字字符或空格）的名称的好方法，如下例所示。
```
SEARCH(' {"My Namespace", "Dimension@Name"}, "Custom:Name[Special_Characters" ', 'Maximum')
```
## CloudWatch 搜索表达式：排除指标架构
到目前为止显示的所有示例都包括指标架构（在大括号中）。省略指标架构的搜索也是有效的。
例如，**SEARCH(' "CPUUtilization" ', 'Average')** 返回所有与字符串 `CPUUtilization` 精确匹配的指标名称、维度名称、维度值和命名空间。在 AWS 指标命名空间中，这可以包括多个服务（包括 Amazon EC2、Amazon ECS、SageMaker AI 等）中的指标。
要将此搜索范围缩小到只有一个 AWS 服务，最佳做法是在指标架构中指定命名空间以及任何必要的维度，如以下示例所示。虽然这会缩小对 `AWS/EC2` 命名空间的搜索范围，但如果您已将 `CPUUtilization` 定义为其他指标的维度值，它仍会返回这些指标的结果。
```
SEARCH(' {AWS/EC2, InstanceType} "CPUUtilization" ', 'Average')
```
或者，您可以在 `SearchTerm` 中添加命名空间，如以下示例所示。但是在本示例中，搜索将与任何 `AWS/EC2` 字符串匹配，即使它是自定义维度名称或值。
```
SEARCH(' "AWS/EC2" MetricName="CPUUtilization" ', 'Average')
```
## CloudWatch 搜索表达式：在搜索中指定属性名称
以下搜索 `"CustomCount1"` 的精确匹配将返回具有该名称的所有指标。
```
SEARCH(' "CustomCount1" ', 'Maximum')
```
但它也返回维度名称、维度值或命名空间为 `CustomCount1` 的指标。要进一步构建搜索，您可以指定要在搜索中查找的对象类型的属性名称。以下示例搜索所有命名空间并返回名为 `CustomCount1` 的指标。
```
SEARCH(' MetricName="CustomCount1" ', 'Maximum')
```
您还可以使用命名空间和维度名称/值对作为属性名称，如以下示例所示。这些示例中的第一个还演示了您也可以将属性名称与部分匹配搜索一起使用。
```
SEARCH(' InstanceType=micro ', 'Average')
```
```
SEARCH(' InstanceType="t2.micro" Namespace="AWS/EC2" ', 'Average')
```
## CloudWatch 搜索表达式：非字母数字字符
非字母数字字符用作分隔符，并标记要将指标名称、维度名称、命名空间名称和搜索词分隔成令牌的位置。当词语被令牌化时，非字母数字字符会被剥离掉，不会出现在令牌中。例如，`Network-Errors_2` 生成令牌 `network`、`errors` 和 `2`。
您的搜索词可以包含任何非字母数字字符。如果这些字符出现在搜索词中，则可以在部分匹配中指定复合令牌。例如，以下所有搜索都将查找名为 `Network-Errors-2` 或 `NetworkErrors2` 的指标。
```
network/errors
network+errors
network-errors
Network_Errors
```
当您进行精确值搜索时，精确搜索中使用的任何非字母数字字符都必须是出现在要搜索的字符串中的正确字符。例如，如果您要查找 `Network-Errors-2`，则 `"Network-Errors-2"` 的搜索成功，但 `"Network_Errors_2"` 搜索不成功。
执行精确匹配搜索时，必须使用反斜杠转义以下字符。
```
" \ ( )
```
例如，要按精确匹配查找指标名称 `Europe\France Traffic(Network)`，请使用搜索词 **"Europe\$1\$1France Traffic\$1(Network\$1)"**
## CloudWatch 搜索表达式：布尔运算符
搜索支持在 `SearchTerm` 中使用布尔运算符 `AND`、`OR` 和 `NOT`。布尔运算符被括在用于将整个搜索词引起来的单引号中。布尔运算符区分大小写，因此 `and`、`or` 和 `not` 作为布尔运算符无效。
您可以在搜索中显式使用 `AND`，例如 **SEARCH('\$1AWS/EC2,InstanceId\$1 network AND packets', 'Average')**。在搜索词之间不使用任何布尔运算符会隐式地搜索它们，就好像存在 `AND` 运算符，因此 **SEARCH(' \$1AWS/EC2,InstanceId\$1 network packets ', 'Average')** 产生相同的搜索结果。
使用 `NOT` 从结果中排除数据子集。例如，**SEARCH(' \$1AWS/EC2,InstanceId\$1 MetricName="CPUUtilization" NOT i-1234567890123456 ', 'Average')** 返回您的所有实例（`i-1234567890123456` 实例除外）的 `CPUUtilization`。您还可以使用 `NOT` 子句作为唯一的搜索词。例如，**SEARCH( 'NOT Namespace=AWS ', 'Maximum')** 产生所有自定义指标（具有不包括 `AWS` 的命名空间的指标）。
您可以在一个查询中使用多个 `NOT` 短语。例如，**SEARCH(' \$1AWS/EC2,InstanceId\$1 MetricName="CPUUtilization" NOT "ProjectA" NOT "ProjectB" ', 'Average')** 返回区域中的所有实例（但维度值为 `ProjectA` 或 `ProjectB` 的实例除外）的 `CPUUtilization`。
您可以组合布尔运算符以进行更强大、更详细的搜索，如以下示例所示。使用括号对运算符进行分组。
接下来的两个示例都返回包含 EC2 和 EBS 命名空间中的 `ReadOps` 的所有指标名称。
```
SEARCH(' (EC2 OR EBS) AND MetricName=ReadOps ', 'Maximum')
```
```
SEARCH(' (EC2 OR EBS) MetricName=ReadOps ', 'Maximum')
```
以下示例将以前的搜索范围缩小为仅包含 `ProjectA` 的结果，这可能是维度的值。
```
SEARCH(' (EC2 OR EBS) AND ReadOps AND ProjectA ', 'Maximum')
```
以下示例使用嵌套分组。它返回所有函数的 `Errors` 的 Lambda 指标，以及名称中包含字符串 `ProjectA` 或 `ProjectB` 的函数的 `Invocations`。
```
SEARCH(' {AWS/Lambda,FunctionName} MetricName="Errors" OR (MetricName="Invocations" AND (ProjectA OR ProjectB)) ', 'Average')
```
## CloudWatch 搜索表达式：使用数学表达式
您可以在图表中的数学表达式内使用搜索表达式。
例如，**SUM(SEARCH(' \$1AWS/Lambda, FunctionName\$1 MetricName="Errors" ', 'Sum'))** 返回您的所有 Lambda 函数的 `Errors` 指标的总和。
对搜索表达式和数学表达式使用单独的行可能会产生更有用的结果。例如，假设您在图表中使用以下两个表达式。第一行显示您的各个 Lambda 函数的单独 `Errors` 行。该表达式的 ID 为 `e1`。第二行添加另一行，以显示所有函数的错误总和。
```
SEARCH(' {AWS/Lambda, FunctionName}, MetricName="Errors" ', 'Sum')
SUM(e1)
```