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

# 查詢
<a name="CWL_QuerySyntax-Lookup"></a>

使用 `lookup` 以查詢資料表中的參考資料豐富查詢結果。查詢資料表包含您上傳至 Amazon CloudWatch Logs 的 CSV 資料。查詢執行時，`lookup`命令會將日誌事件中的欄位與查詢資料表中的欄位相符，並將指定的輸出欄位附加至結果。

針對資料擴充案例使用查詢資料表，例如將使用者 IDs映射至使用者詳細資訊、將產品代碼映射至產品資訊，或將錯誤代碼映射至錯誤描述。

## 建立和管理查詢資料表
<a name="CWL_QuerySyntax-Lookup-tables"></a>

您必須先建立查詢資料表，才能在查詢中使用 `lookup`命令。您可以從 CloudWatch 主控台或使用 Amazon CloudWatch Logs API 建立和管理查詢資料表。

**建立查詢資料表 （主控台）**  


1. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 在導覽窗格中，選擇**設定**，然後選擇**日誌**索引標籤。

1. 捲動至**查詢資料表**，然後選擇**管理**。

1. 選擇**建立查詢資料表**。

1. 輸入查詢資料表的名稱。名稱只能包含英數字元、連字號和底線。

1. (選用) 輸入描述。

1. 上傳 CSV 檔案。檔案必須包含具有資料欄名稱的標頭列、使用 UTF-8 編碼，且不得超過 10 MB。

1. （選用） 指定要加密資料表資料的 AWS KMS 金鑰。

1. 選擇**建立**。

建立查詢資料表之後，您可以在 CloudWatch Logs Insights 查詢編輯器中檢視它。選擇**查詢資料表**索引標籤來瀏覽可用的資料表及其欄位。

若要更新查詢資料表，請選取資料表，然後選擇**動作**、**更新**。上傳新的 CSV 檔案以取代所有現有的內容。若要刪除查詢資料表，請選擇**動作**、**刪除**。

**注意**  
每個 每個帳戶最多可以建立 100 個查詢資料表 AWS 區域。CSV 檔案最多可達 10 MB。您也可以使用 Amazon CloudWatch Logs API 管理查詢資料表。如需詳細資訊，請參閱《*Amazon CloudWatch Logs API 參考*》中的 [CreateLookupTable](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLookupTable.html)。

**注意**  
如果查詢表使用 KMS 金鑰加密，呼叫者必須擁有金鑰 （用於加密查詢表的 KMS 金鑰） 的`kms:Decrypt`許可，才能搭配參考該查詢表的查詢使用 `StartQuery` API。如需詳細資訊，請參閱[使用 加密 CloudWatch Logs 中的查詢資料表 AWS Key Management Service](encrypt-lookup-tables-kms.md)。

## 查詢的查詢語法
<a name="CWL_QuerySyntax-Lookup-syntax"></a>

**命令結構**  
以下顯示此命令的格式。

```
lookup {{table}} {{lookup-field}} as {{log-field}} [,...] {{output-mode}} {{output-field}}[,...]
```

命令使用下列引數：
+ `{{table}}` – 要使用的查詢資料表名稱。
+ `{{lookup-field}}` – 查詢資料表中要比對的欄位。
+ `{{log-field}}` – 日誌事件中要比對的欄位。相符項目完全且區分大小寫。
+ `{{lookup-field}} as {{log-field}} [,...]` – 您可以指定多個以逗號分隔的相符欄位對。指定多個配對時，查詢資料表中的資料列必須符合所有欄位，才能產生結果 (AND 邏輯）。
+ `{{output-mode}}` – 指定輸出欄位如何新增至結果。請使用下列其中一個：
  + `OUTPUT` – 將輸出欄位新增至結果。如果日誌事件中已存在同名的欄位，則會以查詢資料表值覆寫該欄位。如果找不到相符項目，則 欄位會設定為 null。
  + `OUTPUTNEW` – 只有在欄位不存在於日誌事件中時，才會將輸出欄位新增至結果。如果 欄位已有值，則會保留原始值。如果找不到相符項目，則欄位保持不變。
+ `{{output-field}}` – 要新增至結果的查詢資料表中的一個或多個欄位。

**範例：使用使用者詳細資訊來豐富日誌事件**  
假設您有一個包含 `id` 欄位的事件日誌群組，以及名為 的查詢資料表`user_data`，其中包含資料欄 `id`、`name`、 `email`和 `department`。下列查詢會使用查詢表中的使用者名稱、電子郵件和部門來豐富每個日誌事件。

```
fields action, status, name, email, department
| lookup user_data id OUTPUT name, email, department
```

**範例：搭配彙總使用查詢**  
您可以搭配彙總函數使用查詢輸出欄位。下列查詢會使用使用者詳細資訊豐富日誌事件，然後計算依電子郵件地址分組的事件。

```
fields user_id, action, username, email, department
| lookup user_data user_id OUTPUT username, email, department
| stats count(*) by email
```

**範例：搭配篩選條件使用查詢**  
您可以根據查詢傳回的欄位來篩選結果。下列查詢會擴充日誌事件，然後篩選以僅顯示特定部門的事件。

```
fields user_id, action
| lookup user_data user_id OUTPUT username, email, department
| filter department = "Engineering"
```

**範例：使用 OUTPUTNEW 富集而不覆寫**  
如果您的日誌事件已包含 `hostname` 欄位，但有時候是空的，請使用 來填入缺少的值`OUTPUTNEW`，而不會覆寫現有的值。

```
fields srcAddr, hostname
| lookup known_hosts ip_address as srcAddr OUTPUTNEW hostname, region
```

**範例：使用查詢搭配多個相符欄位**  
您可以在多個欄位上進行比對。下列查詢會`dstPort`比對查詢表的 `srcAddr`和 ，以識別已知的網路服務。

```
fields @timestamp, srcAddr, dstAddr, dstPort
| lookup network_services ip_address as srcAddr, port as dstPort OUTPUT service_name, owner
| filter ispresent(service_name)
```