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

# 布林值、比較、數值、日期時間和其他函數
<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` 命令，也可以作為其他函數的引數使用。


| 運算子 | 說明 | 
| --- | --- | 
|  `=`  |  等於  | 
|  `!=`  |  不等於  | 
|  `<`  |  Less than  | 
| `>` |  Greater than  | 
| `<=` |  小於或等於  | 
|  `>=`  |  大於或等於  | 

## 數值運算子
<a name="CWL_QuerySyntax-operations-numeric"></a>

 數值運算接受數值資料類型作為引數，並傳回數值結果。數值運算可用於 `filter` 和 `fields` 命令，也可以作為其他函數的引數使用。


| 作業 | 結果類型 | 說明 | 
| --- | --- | --- | 
|  `abs(a: number)`  |  number  |  絕對值  | 
|  `ceil(a: number)`  |  number  |  無條件進位到上限 (大於 `a` 值的最小整數)  | 
|  `floor(a: number)`  | number |  無條件捨去到下限 (小於 `a` 值的最大整數)  | 
|  `greatest(a: number, ...numbers: number[])`  |  number  |  傳回最大值  | 
|  `least(a: number, ...numbers: number[])`  | number |  傳回最小值  | 
|  `log(a: number)`  |  number  |  自然對數  | 
|  `round(a: number [, d: number])`  |  number  |  四捨五入 的值`a`。使用一個引數，四捨五入到最接近的整數。使用兩個引數，四捨五入到`d`小數位數。 | 
|  `sqrt(a: number)`  |  number  |  平方根  | 
|  `haversine(lat1: number, lon1: number, lat2: number, lon2: number)`  |  number  |  計算經緯度指定的兩個地理點之間的大圓距離，以公里為單位。 | 
|  `toNumber(fieldName: string)`  |  number  |  將字串欄位值轉換為數值。 | 
|  `toInt(fieldName: string)`  |  number  |  將欄位值轉換為整數 (32 位元）。 | 
|  `toLong(fieldName: string)`  |  number  |  將欄位值轉換為長整數 (64 位元）。 | 
|  `toDouble(fieldName: string)`  |  number  |  將欄位值轉換為雙精度浮點數。 | 

## 結構類型
<a name="CWL_QuerySyntax-structure-types"></a>

 地圖或清單是 CloudWatch Logs 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"
```

**範例：空的結果**  
 地圖和清單會被視為字串、數字和日期時間函數的 null。

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

 比較映射和清單到任何其他欄位會導致 `false`。

**注意**  
 `stats` 不支援在 `dedup`、`sort`、 和 `pattern`中使用地圖和清單。

## 日期時間函數
<a name="CWL_QuerySyntax-datetime"></a>

 **日期時間函數** 

 日期時間函數可用於 `fields` 和 `filter` 命令，也可以作為其他函數的引數使用。如果查詢中使用了彙總函數，您可以使用這些函數來建立時段。使用由數字和下列其中一項組成的時段：
+ `ms` 毫秒 
+ `s` 持續 秒 
+ `m` 持續 分鐘 
+ `h` 小時 

 例如，`10m` 是 10 分鐘，`1h` 是 1 小時。

**注意**  
為您的日期時間函數使用最適當的時間單位。CloudWatch Logs 會根據您選擇的時間單位來限制您的請求。例如，它以 60 為上限，做為使用 的任何請求的最大值`s`。因此，如果您指定 `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` 的值四捨五入到指定時間段，然後截斷。例如，`bin(5m)` 將 `@timestamp` 的值四捨五入至最接近的 5 分鐘。<br />您可以使用此操作在查詢中將多筆日誌條目分組在一起。以下範例傳回每小時的例外情況計數。<pre>filter @message like /Exception/ <br />    | stats count(*) as exceptionCount by bin(1h)<br />    | sort exceptionCount desc</pre><br />`bin` 函數支援以下時間單位和縮寫。對於包含多個字元的所有單位和縮寫，支援加上 s 來表示複數。所以 `hr` 和 `hrs` 皆可用來指定時數。+  `millisecond` `ms` `msec` <br />+  `second` `s` `sec` <br />+  `minute` `m` `min` <br />+  `hour` `h` `hr` <br />+  `day` `d`  <br />+  `week` `w`  <br />+  `month` `mo` `mon` <br />+  `quarter` `q` `qtr` <br />+  `year` `y` `yr`  | 
| `datefloor(timestamp: Timestamp, period: Period)` | 時間戳記 | 將時間戳記截斷為指定的期間。例如，`datefloor(@timestamp, 1h)` 將 `@timestamp` 的所有值截斷為半點小時。 | 
| `dateceil(timestamp: Timestamp, period: Period)` | 時間戳記 | 將時間戳記無條件進位到指定期間，然後截斷。例如，`dateceil(@timestamp, 1h)` 將 `@timestamp` 的所有值截斷為整點小時。 | 
| `fromMillis(fieldName: number)` | 時間戳記 | 解譯輸入欄位為自 Unix epoch 以來的毫秒數，並將其轉換為時間戳記。 | 
| `toMillis(fieldName: Timestamp)` | number | 將指定欄位中找到的時間戳記轉換為數字，代表自 Unix epoch 以來的毫秒數。例如：`toMillis(@timestamp)` 會將時間戳記 `2022-01-14T13:18:031.000-08:00` 轉換為 `1642195111000`。 | 
| `now()` | number | 以 epoch 秒為單位，傳回查詢處理開始的時間。此函數不採用引數。<br />您可以使用此值，根據目前時間篩選查詢結果。<br />例如，下列查詢會傳回過去兩個小時內所有 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><br />下列範例會傳回過去五小時內包含單字 `error`或 的所有日誌項目 `failure`<pre>fields @timestamp, @message <br />| filter @message like /(?i)(error|failure)/ <br />| filter toMillis(@timestamp) >= (now() * 1000 - 18000000)</pre> | 
| `parseDate(fieldName: string, format: string [, timezone: string])` | number | 使用 Java DateTimeFormatter 模式將日期字串剖析為 epoch 毫秒。選用`timezone`引數指定用於剖析的時區。<br />範例：`fields parseDate(field, "yyyy-MM-dd", "UTC") as epoch` | 
| `formatDate(timestamp: LogField, format: string [, timezone: string])` | string | 使用 strftime 格式字串格式化時間戳記。也可做為別名 使用`strftime`。選用`timezone`引數會指定要格式化的時區。<br />範例：`fields formatDate(@timestamp, "%Y-%m-%d", "UTC") as date` | 

**注意**  
 目前 CloudWatch Logs Insights 不支援使用人類可讀時間戳記篩選日誌。

## 一般函數
<a name="CWL_QuerySyntax-general-functions"></a>

 **一般函數** 

 一般函數可用於 `fields` 和 `filter` 命令，也可以作為其他函數的引數使用。


| 函式 | 結果類型 | 說明 | 
| --- | --- | --- | 
|  `ispresent(fieldName: LogField)`  |  Boolean  |  如果欄位存在，傳回 `true`  | 
|  `coalesce(fieldName: LogField, ...fieldNames: LogField[])`  |  LogField  |  傳回清單中的第一個非空值  | 
|  `case(cond1, val1, cond2, val2, ..., [default])`  |  LogField  |  依序評估條件，並傳回第一個 true 條件的值。如果沒有條件為 true 且提供了預設值，則 會傳回預設值。最多支援 10 個分支。 | 
|  `if(condition: Boolean, trueValue: LogField, falseValue: LogField)`  |  LogField  |  `trueValue` 如果條件為 true `falseValue`或其他，則評估條件並傳回 。 | 
|  `isNumeric(fieldName: LogField)`  |  Boolean  |  `true` 如果欄位值可以剖析為數字，則傳回 。<br />範例：`filter isNumeric(@duration)` | 
|  `messageSize(fieldName: LogField)`  |  number  |  傳回字串欄位的位元組長度。<br />範例：`fields messageSize(@message) as size` | 
|  `queryStartTime()`  |  number  |  以 epoch 毫秒傳回查詢時段開始時間。 | 
|  `queryEndTime()`  |  number  |  以 epoch 毫秒傳回查詢時段結束時間。 | 
|  `queryTimeRange()`  |  number  |  以毫秒為單位傳回查詢時段持續時間。 | 

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

 **JSON 函數** 

 在 `fields`和 `filter`命令中使用 JSON 函數，並做為其他函數的引數。


| 函式 | 結果類型 | 說明 | 
| --- | --- | --- | 
|  `jsonParse(fieldName: string)`  |  映射 \| 清單 \| 空白  |  當輸入是 JSON 物件或 JSON 陣列的字串表示法時，傳回映射或清單。如果輸入不是其中一個表示法，則傳回空值。 | 
|  `jsonStringify(fieldName: Map \| List)`  |  String  |  從映射或清單資料傳回 JSON 字串。 | 
|  `jsonArraySize(fieldName: LogField)`  |  number  |  傳回 JSON 陣列字串欄位的元素計數。<br />範例：`fields jsonArraySize(Operation) as arrayLen` | 
|  `jsonArrayContains(fieldName: LogField, value: string)`  |  Boolean  |  如果欄位中的 JSON 陣列包含指定的值，則傳回 `true`(1)。針對無效的 JSON、非陣列或空陣列傳回 `false`(0)。使用區分大小寫的比較。<br />範例：`filter jsonArrayContains(@roles, "admin")` | 

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

 **IP 地址字串函數** 

 IP 地址字串函數可用於 `filter` 和 `fields` 命令，也可以作為其他函數的引數使用。


| 函式 | 結果類型 | 說明 | 
| --- | --- | --- | 
| `isValidIp(fieldName: string)` | boolean | 如果欄位是有效的 IPv4 或 IPv6 地址，則會傳回 `true`。 | 
| `isValidIpV4(fieldName: string)` | boolean | 如果欄位是有效的 IPv4 地址，則傳回 `true`。 | 
| `isValidIpV6(fieldName: string)` | boolean | 如果欄位是有效的 IPv6 地址，則傳回 `true`。 | 
| `isIpInSubnet(fieldName: string, subnet: string)` | boolean | 如果欄位是指定 v4 或 v6 子網路內的有效 IPv4 或 IPv6 地址，則傳回 `true`。指定子網路時，請使用 CIDR 標記法，例如 `192.0.2.0/24` 或 `2001:db8::/32`，其中 `192.0.2.0` 或 `2001:db8::` 是 CIDR 區塊的起始位置。 | 
| `isIpv4InSubnet(fieldName: string, subnet: string)` | boolean | 如果欄位是指定 v4 子網路內的有效 IPv4 地址，則傳回 `true`。指定子網路時，請使用 CIDR 標記法，例如 `192.0.2.0/24`，其中 `192.0.2.0` 是 CIDR 區塊的起始位置。 | 
| `isIpv6InSubnet(fieldName: string, subnet: string)` | boolean | 如果欄位是指定 v6 子網路內的有效 IPv6 地址，則傳回 `true`。指定子網路時，請使用 CIDR 標記法，例如 `2001:db8::/32`，其中 `2001:db8::` 是 CIDR 區塊的起始位置。 | 
| `ipv4ToNumber(fieldName: string)` | number | 將 IPv4 地址字串轉換為其數值表示法。 | 
| `isPrivateIP(fieldName: string)` | boolean | `true` 如果 IP 地址位於私有範圍 (RFC 1918)，則傳回 。 | 
| `isPublicIP(fieldName: string)` | boolean | `true` 如果 IP 地址可公開路由，則傳回 。 | 
| `isReservedIP(fieldName: string)` | boolean | `true` 如果 IP 地址位於預留範圍內，則傳回 。 | 

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

 **字串函數** 

 字串函數可用於 `fields` 和 `filter` 命令，也可以作為其他函數的引數使用。


| 函式 | 結果類型 | 說明 | 
| --- | --- | --- | 
| `isempty(fieldName: string)` | Number | 如果欄位遺失或是空白字串，傳回 `1`。 | 
| `isblank(fieldName: string)` | Number | 如果欄位遺失、是空白字串或只包含空格，傳回 `1`。 | 
| `concat(str: string, ...strings: string[])` | string | 串連字串。 | 
| `ltrim(str: string)`<br />`ltrim(str: string, trimChars: string)` | string | 如果函數沒有第二個引數，則會移除字串左側的空格。如果函數有第二個字串引數，則不會移除空格。而是從 `str` 左側移除 `trimChars` 中的字元。例如，`ltrim("xyZxyfooxyZ","xyZ")` 傳回 `"fooxyZ"`。 | 
| `rtrim(str: string)`<br />`rtrim(str: string, trimChars: string)` | string | 如果函數沒有第二個引數，則會移除字串右側的空格。如果函數有第二個字串引數，則不會移除空格。而是從 `str` 右側移除 `trimChars` 的字元。例如，`rtrim("xyZfooxyxyZ","xyZ")` 傳回 `"xyZfoo"`。 | 
| `trim(str: string)`<br />`trim(str: string, trimChars: string)` | string | 如果函數沒有第二個引數，則會移除字串兩側的空格。如果函數有第二個字串引數，則不會移除空格。而是從 `str` 兩側移除 `trimChars` 的字元。例如，`trim("xyZxyfooxyxyZ","xyZ")` 傳回 `"foo"`。 | 
| `strlen(str: string)` | number | 以 Unicode 字碼指標傳回字串的長度。 | 
| `toupper(str: string)` | string | 將字串轉換成大寫。 | 
| `tolower(str: string)` | string | 將字串轉換成小寫。 | 
| `substr(str: string, startIndex: number)`<br />`substr(str: string, startIndex: number, length: number)` | string | 傳回從數字引數指定的索引到字串結尾的子字串。如果函數有第二個數字引數，則是包含要擷取的子字串長度。例如，`substr("xyZfooxyZ",3, 3)` 傳回 `"foo"`。 | 
| `replace(fieldName: string, searchValue: string, replaceValue: string)` | string | 以 `replaceValue` 取代 `fieldName: string` 中出現的所有 `searchValue`。<br />例如：函式 `replace(logGroup,"smoke_test","Smoke")` 搜尋欄位 `logGroup` 中包含字串值 `smoke_test` 的日誌事件，並將值替換為字串 `Smoke`。 | 
| `regexReplace(fieldName: string, pattern: string, replacement: string)` | string | 將符合規則表達式的所有子字串取代`pattern`為 `replacement`。使用 RE2 regex 語法。 | 
| `strcontains(str: string, searchValue: string)`<br />`strcontains(str: string, searchValue: string, caseInsensitive: boolean)` | number | 如果 `str` 包含 `searchValue`，則傳回 1，否則傳回 0。如果第三個參數設定為 `true`，則相符項目不區分大小寫。 | 
| `startsWith(str: string, searchValue: string)` | number | 如果`str`開頭為 `searchValue`，則傳回 1，否則傳回 0。 | 
| `endsWith(str: string, searchValue: string)` | number | 如果`str`以 `searchValue`和 0 結尾，則傳回 1。 | 
| `urlencode(str: string)` | string | URL 編碼字串。 | 
| `urldecode(str: string)` | string | URL 解碼字串。 | 
| `base64encode(str: string)` | string | Base64-encodes字串。 | 
| `base64decode(str: string)` | string | Base64-decodes字串。 | 
| `split(str: string, delimiter: string)` | 陣列 | 依指定的分隔符號分割字串，並傳回子字串陣列。 | 
| `hexToAscii(value: string)` | string | 將十六進位字串轉換為 ASCII 文字。<br />範例：`fields hexToAscii("48656c6c6f") as text` | 
| `hexToDec(value: string)` | number | 將十六進位字串轉換為十進位數字。<br />範例：`fields hexToDec("0xff") as dec` | 
| `decToHex(value: number)` | string | 將小數整數轉換為帶有`0x`字首的小寫十六進位字串。負數會產生`-0x`字首。非整數被截斷。<br />範例：`fields decToHex(255) as hex` |