本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 布尔值、比较、数值、日期时间和其他函数
<a name="CWL_QuerySyntax-operations-functions"></a>

 CloudWatch Logs Insights 支持查询中的许多其他操作和功能，如以下各节所述。

**Topics**
+ [算术运算符](#CWL_QuerySyntax-operations-arithmetic)
+ [布尔运算符](#CWL_QuerySyntax-operations-Boolean)
+ [比较运算符](#CWL_QuerySyntax-operations-comparison)
+ [数值运算符](#CWL_QuerySyntax-operations-numeric)
+ [结构类型](#CWL_QuerySyntax-structure-types)
+ [日期时间函数](#CWL_QuerySyntax-datetime)
+ [常见函数](#CWL_QuerySyntax-general-functions)
+ [JSON 函数](#CWL_QuerySyntax-json-functions)
+ [IP 地址字符串函数](#CWL_QuerySyntax-IPaddress-functions)
+ [字符串函数](#CWL_QuerySyntax-string-functions)

## 算术运算符
<a name="CWL_QuerySyntax-operations-arithmetic"></a>

 算术运算接受数值数据类型作为参数并返回数值结果。在 `filter` 和 `fields` 命令中使用算术运算并将其用作其他函数的参数。


| 操作 | 说明 | 
| --- | --- | 
|  `a + b` |  加  | 
|  `a - b` |  减  | 
|  `a * b` |  乘  | 
|  `a / b` |  除  | 
|  `a ^ b` |   幂（`2 ^ 3` 返回 `8`）   | 
|  `a % b` |   余额或模数（`10 % 3` 返回 `1`）   | 

## 布尔运算符
<a name="CWL_QuerySyntax-operations-Boolean"></a>

 使用布尔运算符 `and`、`or` 和 `not`。

**注意**  
 仅在返回 **TRUE** 或 **FALSE** 值的函数中使用布尔运算符。

## 比较运算符
<a name="CWL_QuerySyntax-operations-comparison"></a>

 比较运算接受所有数据类型作为参数，并返回布尔值结果。在 `filter` 命令中使用比较运算并将其用作其他函数的参数。


| 运算符 | 说明 | 
| --- | --- | 
|   `=`   |   Equal   | 
|   `!=`   |   Not equal   | 
|   `<`   |   Less than   | 
|  `>` |   Greater than   | 
|  `<=` |   小于或等于   | 
|   `>=`   |   大于或等于   | 

## 数值运算符
<a name="CWL_QuerySyntax-operations-numeric"></a>

 数值运算接受数值数据类型作为参数并返回数值结果。在 `filter` 和 `fields` 命令中使用数值运算并将其用作其他函数的参数。


| 操作 | 结果类型 | 说明 | 
| --- | --- | --- | 
|   `abs(a: number)`   |   number   |   绝对值   | 
|   `ceil(a: number)`   |   数字   |   舍入到上限（大于 `a` 的值的最小整数）   | 
|   `floor(a: number)`   |  数字 |   舍入到下限（小于 `a` 的值的最大整数）   | 
|   `greatest(a: number, ...numbers: number[])`   |   数字   |   返回最大值   | 
|   `least(a: number, ...numbers: number[])`   |  数字 |   返回最小值   | 
|   `log(a: number)`   |   数字   |   自然对数   | 
|   `sqrt(a: number)`   |   数字   |   平方根   | 

## 结构类型
<a name="CWL_QuerySyntax-structure-types"></a>

 地图或列表是 L CloudWatch ogs Insights 中的一种结构类型，允许您访问和使用属性进行查询。

**示例：获取映射或列表**  
 使用 `jsonParse` 可以将 json 字符串字段解析为地图或列表。

```
fields jsonParse(@message) as json_message
```

**示例：访问属性**  
 使用点访问运算符（map.attribute）可以访问映射中的项。如果映射中的某属性包含特殊字符，请使用反引号将属性名称括起来（map.attributes.`special.char`）。

```
fields jsonParse(@message) as json_message
| stats count() by json_message.status_code
```

 使用方括号访问运算符（list[index]）可以检索列表中特定位置的项。

```
fields jsonParse(@message) as json_message
| filter json_message.users[1].action = "PutData"
```

 当键名中出现特殊字符时，请用反引号（``）将特殊字符括起来。

```
fields jsonParse(@message) as json_message
| filter json_message.`user.id` = "123"
```

**示例：空结果**  
 对于字符串、数字和日期时间函数，映射和列表会被视为空值。

```
fields jsonParse(@message) as json_message
| display toupper(json_message)
```

 将映射和列表与任何其他字段进行比较会得出 `false`。

**注意**  
 不支持在 `dedup`、`pattern`、`sort` 和 `stats` 中使用映射和列表。

## 日期时间函数
<a name="CWL_QuerySyntax-datetime"></a>

 **日期时间函数** 

 在 `fields` 和 `filter` 命令中使用日期时间函数并将其用作其他函数的参数。使用这些函数为使用聚合函数的查询创建时间存储桶。使用由数字和下列项之一组成的时间段：
+ `ms` 代表毫秒 
+ `s` 代表秒 
+ `m` 代表分钟 
+ `h` 代表小时 

 例如，`10m` 为 10 分钟，`1h` 为 1 小时。

**注意**  
为日期时间函数使用最合适的时间单位。 CloudWatch 日志会根据您选择的时间单位对您的请求进行上限。例如，对于使用 `s` 的任何请求，它将最大值限制为 60。因此，如果您指定`bin(300s)`， CloudWatch Logs 实际上将其实现为 60 秒，因为 60 是一分钟内的秒数，因此 CloudWatch Logs 不会使用大于 60 的数字`s`。要创建 5 分钟的存储桶，请改用 `bin(5m)`。  
`ms` 的上限为 1000，`s` 和 `m` 的上限为 60，`h` 的上限为 24。

下表包含可在查询命令中使用的不同日期时间函数列表。该表列出了每个函数的结果类型，并包含对每个函数的描述。

**提示**  
 在创建查询命令时，您可以使用时间间隔选择器选择要查询的时间段。例如，您可以设置 5 到 30 分钟的时间间隔；1、3 和 12 小时间隔；或者自定义时间范围。您还可以设置特定日期之间的时间段。


| 函数 | 结果类型 | 说明 | 
| --- | --- | --- | 
|  `bin(period: Period)` |  Timestamp |  将 `@timestamp` 的值四舍五入到指定的时间段，然后截断。例如，`bin(5m)` 将 `@timestamp` 的值四舍五入到最近的 5 分钟。 您可以使用它将某个查询中的多个日志条目分为一组。以下示例返回每小时的异常数量。 <pre>filter @message like /Exception/ <br />    | stats count(*) as exceptionCount by bin(1h)<br />    | sort exceptionCount desc</pre> `bin` 函数支持以下时间单位和缩写。对于所有包含多个字符的单位和缩写，支持添加复数形式。这样，`hr` 和 `hrs` 都可以指定小时数。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html)  | 
|  `datefloor(timestamp: Timestamp, period: Period)` |  Timestamp |  将时间戳截断到指定的时间段。例如，`datefloor(@timestamp, 1h)` 将 `@timestamp` 的所有值截断至小时底部。  | 
|  `dateceil(timestamp: Timestamp, period: Period)` |  Timestamp |  将时间戳向上舍入到指定的时间段，然后截断。例如，`dateceil(@timestamp, 1h)` 将 `@timestamp` 的所有值截断至小时顶部。  | 
|  `fromMillis(fieldName: number)` |  Timestamp |  将输入字段解释为自 Unix epoch 以来的毫秒数并将其转换为时间戳。  | 
|  `toMillis(fieldName: Timestamp)` |  数字 |  将在命名字段中找到的时间戳转换为表示自 Unix epoch 以来毫秒数的数字。例如，`toMillis(@timestamp)` 将时间戳 `2022-01-14T13:18:031.000-08:00` 转换为 `1642195111000`。  | 
|  `now()`  |  数字  |  返回查询处理开始的时间，以 epoch 秒为单位。此函数不接受任何参数。 您可以使用它根据当前时间筛选查询结果。 例如，以下查询将返回过去两小时内的所有 4xx 错误： <pre>parse @message "Status Code: *;" as statusCode\n <br />| filter statusCode >= 400 and statusCode <= 499  \n <br />| filter toMillis(@timestamp) >= (now() * 1000 - 7200000)</pre> 以下示例会返回过去五小时内所有包含 `error` 或 `failure` 字样的日志条目 <pre>fields @timestamp, @message <br />| filter @message like /(?i)(error|failure)/ <br />| filter toMillis(@timestamp) >= (now() * 1000 - 18000000)</pre>  | 

**注意**  
 目前， CloudWatch Logs Insights 不支持筛选带有人类可读时间戳的日志。

## 常见函数
<a name="CWL_QuerySyntax-general-functions"></a>

 **常见函数** 

 在 `fields` 和 `filter` 命令中使用常规函数并将其用作其他函数的参数。


| 函数 | 结果类型 | 说明 | 
| --- | --- | --- | 
|   `ispresent(fieldName: LogField)`   |   布尔值   |   如果字段存在，则返回 `true`   | 
|   `coalesce(fieldName: LogField, ...fieldNames: LogField[])`   |   LogField   |   返回列表中的第一个非 null 值   | 

## JSON 函数
<a name="CWL_QuerySyntax-json-functions"></a>

 **json 函数** 

 在 `fields` 和 `filter` 命令中使用 JSON 函数并将其用作其他函数的参数。


| 函数 | 结果类型 | 说明 | 
| --- | --- | --- | 
|   `jsonParse(fieldName: string)`   |   映射 \$1 列表 \$1 空   |   当输入为 JSON 对象的字符串表示形式或 JSON 数组时，返回映射或列表。如果输入不是其中一种表示形式，则返回空值。  | 
|   `jsonStringify(fieldName: Map \| List)`   |   字符串   |   从映射或列表数据中返回 JSON 字符串。  | 

## IP 地址字符串函数
<a name="CWL_QuerySyntax-IPaddress-functions"></a>

 **IP 地址字符串函数** 

 在 `filter` 和 `fields` 命令中使用 IP 地址字符串函数并将其用作其他函数的参数。


| 函数 | 结果类型 | 说明 | 
| --- | --- | --- | 
|  `isValidIp(fieldName: string)` |  布尔值 |  `true`如果该字段为有效 IPv4 或 IPv6 地址，则返回。  | 
|  `isValidIpV4(fieldName: string)` |  布尔值 |  `true`如果该字段是有效 IPv4 的地址，则返回。  | 
|  `isValidIpV6(fieldName: string)` |  布尔值 |  `true`如果该字段是有效 IPv6 的地址，则返回。  | 
|  `isIpInSubnet(fieldName: string, subnet: string)` |  布尔值 |  `true`如果该字段为指定的 v4 IPv4 或 v6 子网内的有效 IPv6 地址或地址，则返回。指定子网时，请使用 CIDR 表示法（例如 `192.0.2.0/24` 或 `2001:db8::/32`），其中 `192.0.2.0` 或 `2001:db8::` 是 CIDR 块的起点。  | 
|  `isIpv4InSubnet(fieldName: string, subnet: string)` |  布尔值 |  `true`如果该字段是指定 v4 子网内的有效 IPv4 地址，则返回。指定子网时，请使用 CIDR 表示法（例如 `192.0.2.0/24`），其中 `192.0.2.0` 是 CIDR 块的起点。  | 
|  `isIpv6InSubnet(fieldName: string, subnet: string)` |  布尔值 |  `true`如果该字段是指定 v6 子网内的有效 IPv6 地址，则返回。指定子网时，请使用 CIDR 表示法（例如 `2001:db8::/32`），其中 `2001:db8::` 是 CIDR 块的起点。  | 

## 字符串函数
<a name="CWL_QuerySyntax-string-functions"></a>

 **字符串函数** 

 在 `fields` 和 `filter` 命令中使用字符串函数并将其用作其他函数的参数。


| 函数 | 结果类型 | 说明 | 
| --- | --- | --- | 
|  `isempty(fieldName: string)` |  数字 |  如果字段缺失或为空字符串，则返回 `1`。  | 
|  `isblank(fieldName: string)` |  数字 |  如果字段缺失或为空字符串，或只包含空格，则返回 `1`。  | 
|  `concat(str: string, ...strings: string[])` |  字符串 |  连结字符串。  | 
|  `ltrim(str: string)` `ltrim(str: string, trimChars: string)` |  字符串 |  如果函数没有第二个参数，它将删除字符串左侧的空格。如果函数有第二个字符串参数，它将不会删除空格。相反，它会从 `str` 左侧删除 `trimChars` 中的字符。例如，`ltrim("xyZxyfooxyZ","xyZ")` 将返回 `"fooxyZ"`。  | 
|  `rtrim(str: string)` `rtrim(str: string, trimChars: string)` |  字符串 |  如果函数没有第二个参数，它将删除字符串右侧的空格。如果函数有第二个字符串参数，它将不会删除空格。相反，它会从 `str` 右侧删除 `trimChars` 字符。例如，`rtrim("xyZfooxyxyZ","xyZ")` 将返回 `"xyZfoo"`。  | 
|  `trim(str: string)` `trim(str: string, trimChars: string)` |  字符串 |  如果函数没有第二个参数，它将删除字符串两端的空格。如果函数有第二个字符串参数，它将不会删除空格。相反，它会从 `str` 两端删除 `trimChars` 字符。例如，`trim("xyZxyfooxyxyZ","xyZ")` 将返回 `"foo"`。  | 
|  `strlen(str: string)` |  数字 |  返回 Unicode 代码点中字符串的长度。  | 
|  `toupper(str: string)` |  字符串 |  将字符串转换为大写。  | 
|  `tolower(str: string)` |  字符串 |  将字符串转换为小写。  | 
|  `substr(str: string, startIndex: number)` `substr(str: string, startIndex: number, length: number)` |  字符串 |  返回从由数值参数指定的索引到字符串末尾的子字符串。如果该函数具有二个参数，它包含要检索的子字符串的长度。例如，`substr("xyZfooxyZ",3, 3)` 将返回 `"foo"`。  | 
|  `replace(fieldName: string, searchValue: string, replaceValue: string)` |  字符串 |  将 `fieldName: string` 中出现的所有 `searchValue` 替换为 `replaceValue`。 例如，函数 `replace(logGroup,"smoke_test","Smoke")` 搜索录入事件，其中字段 `logGroup` 包含字符串值 `smoke_test`，并使用字符串 `Smoke` 替换该值。  | 
|  `strcontains(str: string, searchValue: string)` |  数字 |  如果 `str` 包含 `searchValue`，则返回 1，否则返回 0。  |