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

# lookup
<a name="CWL_QuerySyntax-Lookup"></a>

使用`lookup`查找表中的参考数据来丰富查询结果。查询表包含您上传到 Amazon Logs 的 CSV CloudWatch 数据。运行查询时，该`lookup`命令会将日志事件中的字段与查找表中的字段进行匹配，并将指定的输出字段附加到结果中。

对数据丰富场景使用查找表，例如 IDs将用户映射到用户详细信息、将产品代码映射到产品信息或将错误代码映射到错误描述。

## 创建和管理对照表
<a name="CWL_QuerySyntax-Lookup-tables"></a>

必须先创建对照表，然后才能在查询中使用该`lookup`命令。您可以通过 CloudWatch 控制台或使用 Amazon L CloudWatch ogs API 创建和管理查询表。

**创建对照表（控制台）**  


1. 打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。

1. 在导航窗格中，选择 “**设置”**，然后选择 “**日志**” 选项卡。

1. 滚动到 “**查找表**”，然后选择 “**管理**”。

1. 选择 “**创建对照表”**。

1. 输入查找表的名称。名称只能包含字母数字字符、连字符和下划线。

1. （可选）输入描述。

1. 上传 CSV 文件。该文件必须包含带有列名的标题行，使用 UTF-8 编码，且不超过 10 MB。

1. （可选）指定用于加密表数据的密 AWS KMS 钥。

1. 选择**创建**。

创建对照表后，您可以在 L CloudWatch ogs Insights 查询编辑器中查看该表。选择 “**查找表**” 选项卡以浏览可用表及其字段。

要更新查找表，请选择该表，然后选择**操作**、**更新**。上传新的 CSV 文件以替换所有现有内容。要删除对照表，请选择**操作**，**删除**。

**注意**  
每个账户最多可以创建 100 个查询表 AWS 区域。CSV 文件的最大大小为 10 MB。您也可以使用 Amazon CloudWatch 日志 API 管理查询表。有关更多信息，请参阅 *Amazon CloudWatch 日志 API 参考[CreateLookupTable](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLookupTable.html)*中的。

**注意**  
如果使用 KMS 密钥对查找表进行加密，则调用者必须拥有该密钥（用于加密查找表的 KMS 密钥）的`kms:Decrypt`权限，才能将 `StartQuery` API 用于引用该查找表的查询。有关更多信息，请参阅 [使用加密 CloudWatch 日志中的查找表 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
```

**示例：使用包含多个匹配字段的查找**  
您可以在多个字段上进行匹配。以下查询将查询表`srcAddr`与`dstPort`对照表进行匹配，以识别已知的网络服务。

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