As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# lookup
Use `lookup` para enriquecer os resultados da consulta com dados de referência de uma tabela de pesquisa. Uma tabela de pesquisa contém dados CSV que você carrega para o Amazon CloudWatch Logs. Quando uma consulta é executada, o `lookup` comando combina um campo em seus eventos de log com um campo na tabela de pesquisa e acrescenta os campos de saída especificados aos resultados.
Use tabelas de pesquisa para cenários de enriquecimento de dados, como mapear detalhes do usuário IDs para o usuário, códigos do produto para informações do produto ou códigos de erro para descrições de erros.
## Criação e gerenciamento de tabelas de pesquisa
Antes de usar o `lookup` comando em uma consulta, você deve criar uma tabela de pesquisa. Você pode criar e gerenciar tabelas de pesquisa a partir do CloudWatch console ou usando a API Amazon CloudWatch Logs.
**Para criar uma tabela de pesquisa (console)**
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Configurações** e, em seguida, escolha a guia **Registros**.
1. Role até **Pesquisar tabelas** e escolha **Gerenciar**.
1. Escolha **Criar tabela de pesquisa**.
1. Insira um nome para a tabela de pesquisa. O nome só pode conter caracteres alfanuméricos, hífens e sublinhados.
1. (Opcional) Insira uma descrição.
1. Faça upload de um arquivo CSV. O arquivo deve incluir uma linha de cabeçalho com nomes de colunas, usar a codificação UTF-8 e não exceder 10 MB.
1. (Opcional) Especifique uma AWS KMS chave para criptografar os dados da tabela.
1. Escolha **Criar**.
Depois de criar uma tabela de pesquisa, você pode visualizá-la no editor de consultas do CloudWatch Logs Insights. Escolha a guia **Pesquisar tabelas** para procurar tabelas disponíveis e seus campos.
Para atualizar uma tabela de pesquisa, selecione a tabela e escolha **Ações**, **Atualizar**. Faça upload de um novo arquivo CSV para substituir todo o conteúdo existente. Para excluir uma tabela de pesquisa, escolha **Ações**, **Excluir**.
**nota**
Você pode criar até 100 tabelas de pesquisa por conta por Região da AWS. Os arquivos CSV podem ter até 10 MB. Você também pode gerenciar tabelas de pesquisa usando a API Amazon CloudWatch Logs. Para obter mais informações, consulte [CreateLookupTable](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLookupTable.html)a *Referência da API Amazon CloudWatch Logs*.
**nota**
Se a tabela de pesquisa for criptografada com uma chave KMS, o chamador deverá ter a `kms:Decrypt` permissão na chave (a chave KMS usada para criptografar a tabela de pesquisa) para usar a `StartQuery` API com uma consulta que faça referência a essa tabela de pesquisa. Para obter mais informações, consulte [Criptografe tabelas de pesquisa em CloudWatch registros usando AWS Key Management Service](encrypt-lookup-tables-kms.md).
## Sintaxe de consulta para pesquisa
**Estrutura do comando**
O seguinte mostra o formato desse comando.
```
lookup table lookup-field as log-field [,...] output-mode output-field[,...]
```
O comando usa os seguintes argumentos:
+ `table`— O nome da tabela de pesquisa a ser usada.
+ `lookup-field`— O campo na tabela de pesquisa a ser comparado.
+ `log-field`— O campo em seu registro de eventos correspondente. A correspondência é exata e diferencia maiúsculas de minúsculas.
+ `output-mode`— Especifique `OUTPUT` para adicionar os campos de saída aos resultados. Se um campo com o mesmo nome já existir no evento de log, ele será substituído.
+ `output-field`— Um ou mais campos da tabela de pesquisa para adicionar aos resultados.
**Exemplo: enriqueça eventos de registro com detalhes do usuário**
Suponha que você tenha um grupo de registros com eventos que contêm um `id` campo e uma tabela de pesquisa chamada `user_data` com colunas `id` `name``email`,, `department` e. A consulta a seguir enriquece cada evento de log com o nome do usuário, e-mail e departamento da tabela de pesquisa.
```
fields action, status, name, email, department
| lookup user_data id OUTPUT name, email, department
```
**Exemplo: Use a pesquisa com agregação**
Você pode usar campos de saída de pesquisa com funções de agregação. A consulta a seguir enriquece os eventos de log com detalhes do usuário e, em seguida, conta os eventos agrupados por endereço de e-mail.
```
fields user_id, action, username, email, department
| lookup user_data user_id OUTPUT username, email, department
| stats count(*) by email
```
**Exemplo: Use a pesquisa com filtro**
Você pode filtrar os resultados com base nos campos retornados pela pesquisa. A consulta a seguir enriquece os eventos de registro e depois filtra para mostrar somente os eventos de um departamento específico.
```
fields user_id, action
| lookup user_data user_id OUTPUT username, email, department
| filter department = "Engineering"
```