# Sintaxe de expressão de pesquisa do CloudWatch
Uma expressão de pesquisa válida tem o formato a seguir.
```
SEARCH(' {Namespace, DimensionName1, DimensionName2, ...} SearchTerm', 'Statistic')
```
Por exemplo:
```
SEARCH('{AWS/EC2,InstanceId} MetricName="CPUUtilization"', 'Average')
```
+ A primeira parte da consulta depois da palavra `SEARCH`, entre chaves, é o *metric schema (esquema de métrica)* a ser pesquisado. O esquema de métrica contém um namespace de métrica e um ou mais nomes de dimensão. A inclusão de um esquema de métrica em uma consulta de pesquisa é opcional. Se especificado, o esquema de métrica deve conter um namespace e pode conter um ou mais nomes de dimensão que são válidos nesse namespace.
Você não precisa usar aspas dentro do esquema de métrica, a menos que um nome de dimensão ou namespace inclua espaços ou caracteres não alfanuméricos. Nesse caso, você deve colocar o nome que contém esses caracteres entre aspas duplas.
+ O `SearchTerm` também é opcional, mas uma pesquisa válida deve conter o esquema de métrica, o `SearchTerm` ou ambos. O `SearchTerm` geralmente contém um ou mais IDs de métrica, nomes de métrica ou valores de dimensão. O `SearchTerm` pode incluir vários termos para serem pesquisados, tanto por correspondência parcial como por correspondência exata. Ele também pode conter operadores boolianos.
Usar um ID de conta em um `SearchTerm` só funciona em contas configuradas como contas de monitoramento para a observabilidade entre contas do CloudWatch. A sintaxe de um ID de conta no `SearchTerm` é `:aws.AccountId = 444455556666`. Você também pode usar `'LOCAL'` para especificar a própria conta de monitoramento: `:aws.AccountId = 'LOCAL'`
Para obter mais informações, consulte [Observabilidade entre contas do CloudWatch](CloudWatch-Unified-Cross-Account.md).
O `SearchTerm` pode incluir um ou mais designadores, como `MetricName=`, conforme este exemplo, mas o uso de designadores não é obrigatório.
O esquema de métrica e `SearchTerm` devem estar juntos entre aspas simples.
+ O `Statistic` é o nome de qualquer estatística válida do CloudWatch. Ele deve ser colocado entre aspas simples. Para obter mais informações, consulte [Statistics](cloudwatch_concepts.md#Statistic).
O exemplo anterior pesquisa o namespace `AWS/EC2` para as métricas que têm `InstanceId` como nome de uma dimensão. Ele retorna todas as métricas `CPUUtilization` que encontra, com o gráfico exibindo a estatística `Average`.
Uma expressão de pesquisa pode encontrar somente métricas que relataram dados nas últimas duas semanas.
**Limites da expressão de pesquisa**
O tamanho máximo da consulta da expressão de pesquisa é de 1024 caracteres. Você pode ter até 100 expressões de pesquisa em um gráfico. Um gráfico pode exibir até 500 séries temporais.
## Expressões de pesquisa do CloudWatch: tokenização
Quando você especifica um `SearchTerm`, a função de pesquisa busca *tokens*, que são substrings geradas automaticamente pelo CloudWatch de todos os nomes de métrica, nomes de dimensão, valores de dimensão e namespaces. O CloudWatch gera tokens diferenciados pela capitalização camel-case na string original. Os caracteres numéricos também são usados como o início de novos tokens, e os caracteres não alfanuméricos funcionam como delimitadores, criando tokens antes e depois dos caracteres não alfanuméricos.
Uma string contínua do mesmo tipo do caractere delimitador de token resulta em um token.
Todos os tokens são gerados em letras minúsculas. A tabela a seguir mostra alguns exemplos de tokens gerados.
| String original | Tokens gerados |
| --- | --- |
| CustomCount1 | `customcount1`, `custom`, `count`, `1` |
| SDBFailure | `sdbfailure`, `sdb`, `failure` |
| Project2-trial333 | `project2trial333`, `project`, `2`, `trial`, `333` |
## Expressões de pesquisa do CloudWatch: correspondências parciais
Quando você especifica um `SearchTerm`, o termo de pesquisa também é tokenizado. O CloudWatch localiza métricas com base em correspondências parciais, que são correspondências de um único token gerado a partir do termo de pesquisa para um único token gerado a partir de um namespace, nome ou valor da dimensão ou nome da métrica.
As pesquisas de correspondência parcial de um único token não distinguem letras maiúsculas de minúsculas. Por exemplo, o uso de qualquer um dos seguintes termos de pesquisa pode retornar a métrica `CustomCount1`:
+ `count`
+ `Count`
+ `COUNT`
No entanto, o uso de `couNT` como um termo de pesquisa não localiza `CustomCount1`, pois a capitalização no termo de pesquisa `couNT` é tokenizada em `cou` e `NT`.
As pesquisas também podem corresponder a tokens compostos, que são vários tokens que aparecem consecutivamente no nome original. Para corresponder a um token composto, a pesquisa diferencia maiúsculas de minúsculas. Por exemplo, se o termo original for `CustomCount1`, pesquisas por `CustomCount` ou `Count1` serão bem-sucedidas, mas pesquisas por `customcount` ou `count1` não.
## Expressões de pesquisa do CloudWatch: correspondências exatas
Você pode definir uma pesquisa para localizar apenas correspondências exatas do termo de pesquisa usando aspas duplas ao redor da parte do termo de pesquisa que requer uma correspondência exata. Essas aspas duplas são inseridas entre as aspas simples usadas em torno de todo o termo de pesquisa. Por exemplo, **SEARCH(' \$1MyNamespace\$1, "CustomCount1" ', 'Maximum')** localizará a string exata `CustomCount1` se ela existir como um nome da métrica, nome ou valor da dimensão no namespace chamado `MyNamespace`. No entanto, as pesquisas **SEARCH(' \$1MyNamespace\$1, "customcount1" ', 'Maximum')** ou **SEARCH(' \$1MyNamespace\$1, "Custom" ', 'Maximum')** não localizam essa string.
Você pode combinar termos de correspondência parcial e termos de correspondência exata em uma única expressão de pesquisa. Por exemplo, **SEARCH(' \$1AWS/NetworkELB, LoadBalancer\$1 "ConsumedLCUs" OR flow ', 'Maximum')** retorna a métrica do Elastic Load Balancing chamada `ConsumedLCUs` e todas as métricas ou dimensões do Elastic Load Balancing que contenham o token `flow`.
O uso da correspondência exata também é uma boa maneira de localizar nomes com caracteres especiais, como caracteres não alfanuméricos ou espaços, conforme o exemplo a seguir.
```
SEARCH(' {"My Namespace", "Dimension@Name"}, "Custom:Name[Special_Characters" ', 'Maximum')
```
## Expressões de pesquisa do CloudWatch: excluir um esquema de métrica
Todos os exemplos mostrados até agora incluem um esquema de métrica entre chaves. As pesquisas que omitem um esquema de métrica também são válidas.
Por exemplo, **SEARCH(' "CPUUtilization" ', 'Average')** retorna todos os nomes de métrica, nomes de dimensão, valores de dimensão e namespaces que são uma correspondência exata para a string `CPUUtilization`. Nos namespaces de métricas da AWS, isso pode incluir métricas de vários produtos, incluindo Amazon EC2, Amazon ECS, SageMaker AI, entre outros.
Para restringir essa pesquisa a apenas um serviço da AWS, a prática recomendada é especificar o namespace e todas as dimensões necessárias no esquema de métrica, como no exemplo a seguir. Embora isso restrinja a pesquisa ao namespace `AWS/EC2`, ela ainda retornaria resultados de outras métricas se você tivesse definido `CPUUtilization` como um valor da dimensão para essas métricas.
```
SEARCH(' {AWS/EC2, InstanceType} "CPUUtilization" ', 'Average')
```
Como alternativa, você pode adicionar o namespace no `SearchTerm` como no exemplo a seguir. No entanto, neste exemplo, a pesquisa corresponderia a qualquer string `AWS/EC2`, mesmo se ela fosse um valor ou nome de dimensão personalizados.
```
SEARCH(' "AWS/EC2" MetricName="CPUUtilization" ', 'Average')
```
## Expressões de pesquisa do CloudWatch: especificar nomes de propriedade na pesquisa
A pesquisa de correspondência exata por `"CustomCount1"` a seguir retorna todas as métricas exatamente com esse nome.
```
SEARCH(' "CustomCount1" ', 'Maximum')
```
No entanto, ela também retorna métricas com nomes de dimensão, valores de dimensão ou namespaces de `CustomCount1`. Para estruturar ainda mais sua pesquisa, você pode especificar o nome de propriedade do tipo de objeto que deseja localizar nas pesquisas. O exemplo a seguir pesquisa todos os namespaces e retorna métricas chamadas `CustomCount1`.
```
SEARCH(' MetricName="CustomCount1" ', 'Maximum')
```
Você também pode usar pares nome/valor de dimensão e namespaces como nomes de propriedade, conforme os exemplos a seguir. O primeiro desses exemplos também ilustra que você pode usar nomes de propriedade com pesquisas de correspondência parcial.
```
SEARCH(' InstanceType=micro ', 'Average')
```
```
SEARCH(' InstanceType="t2.micro" Namespace="AWS/EC2" ', 'Average')
```
## Expressões de pesquisa do CloudWatch: caracteres não alfanuméricos
Os caracteres não alfanuméricos servem como delimitadores e marcam onde os nomes de métricas, as dimensões, os namespaces e os termos de pesquisa devem ser separados em tokens. Quando os termos são tokenizados, os caracteres não alfanuméricos são removidos e não aparecem nos tokens. Por exemplo, `Network-Errors_2` gera os tokens `network`, `errors`, e `2`.
O termo de pesquisa pode incluir qualquer caractere não alfanumérico. Se esses caracteres aparecerem no termo de pesquisa, eles poderão especificar tokens compostos em uma correspondência parcial. Por exemplo, todas as pesquisas a seguir localizariam métricas chamadas `Network-Errors-2` ou `NetworkErrors2`.
```
network/errors
network+errors
network-errors
Network_Errors
```
Quando você estiver fazendo uma pesquisa de valor exato, qualquer caractere não alfanumérico usado na pesquisa exata deverá ser o caractere correto que aparece na string que está sendo pesquisada. Por exemplo, se você quiser encontrar `Network-Errors-2`, a pesquisa por `"Network-Errors-2"` será bem-sucedida, mas uma pesquisa por `"Network_Errors_2"` não.
Quando você realizar uma pesquisa de correspondência exata, os caracteres a seguir deverão ser recuados com uma barra invertida.
```
" \ ( )
```
Por exemplo, para encontrar o nome da métrica `Europe\France Traffic(Network)` por correspondência exata, use o termo de pesquisa **"Europe\$1\$1France Traffic\$1(Network\$1)"**
## Expressões de pesquisa do CloudWatch: operadores boolianos
A pesquisa oferece suporte ao uso de operadores boolianos `AND`, `OR` e `NOT` no `SearchTerm`. Os operadores boolianos são inseridos entre aspas simples usadas ao redor de todo o termo de pesquisa. Os operadores boolianos fazem distinção de maiúsculas e minúsculas, portanto `and`, `or` e `not` não são válidos como operadores boolianos.
Você pode usar o `AND` explicitamente na pesquisa, como o **SEARCH('\$1AWS/EC2,InstanceId\$1 network AND packets', 'Average')**. Não usar nenhum operador booliano entre os termos de pesquisa vai fazer com que eles sejam implicitamente pesquisados como se houvesse um operador do `AND`, portanto, o **SEARCH(' \$1AWS/EC2,InstanceId\$1 network packets ', 'Average')** gera os mesmos resultados de pesquisa.
Use `NOT` para excluir subconjuntos de dados dos resultados. Por exemplo, o **SEARCH(' \$1AWS/EC2,InstanceId\$1 MetricName="CPUUtilization" NOT i-1234567890123456 ', 'Average')** retorna o `CPUUtilization` para todas as suas instâncias, exceto para a instância do `i-1234567890123456`. Você também pode usar uma cláusula `NOT` como o único termo de pesquisa. Por exemplo, o **SEARCH( 'NOT Namespace=AWS ', 'Maximum')** gera todas as suas métricas personalizadas (métricas com namespaces que não incluem o `AWS`).
Você pode usar várias expressões `NOT` em uma consulta. Por exemplo, o **SEARCH(' \$1AWS/EC2,InstanceId\$1 MetricName="CPUUtilization" NOT "ProjectA" NOT "ProjectB" ', 'Average')** retorna o `CPUUtilization` de todas as instâncias na região, exceto para aquelas com valores de dimensão do `ProjectA` ou do `ProjectB`.
Você pode combinar operadores boolianos para realizar pesquisas mais eficientes e detalhadas, conforme os exemplos a seguir. Use parênteses para agrupar os operadores.
Os dois exemplos a seguir retornam todos os nomes de métricas que contêm `ReadOps` de ambos os namespaces do EC2 e do EBS.
```
SEARCH(' (EC2 OR EBS) AND MetricName=ReadOps ', 'Maximum')
```
```
SEARCH(' (EC2 OR EBS) MetricName=ReadOps ', 'Maximum')
```
O exemplo a seguir restringe a pesquisa anterior a somente os resultados que incluem `ProjectA`, o que pode ser o valor de uma dimensão.
```
SEARCH(' (EC2 OR EBS) AND ReadOps AND ProjectA ', 'Maximum')
```
O exemplo a seguir usa agrupamentos aninhados. Ele retorna métricas do Lambda para `Errors` de todas as funções, e `Invocations` de funções com nomes que incluem as strings `ProjectA` ou `ProjectB`.
```
SEARCH(' {AWS/Lambda,FunctionName} MetricName="Errors" OR (MetricName="Invocations" AND (ProjectA OR ProjectB)) ', 'Average')
```
## Expressões de pesquisa do CloudWatch: usar expressões matemáticas
Você pode usar uma expressão de pesquisa dentro de expressões matemáticas em um gráfico.
Por exemplo, **SUM(SEARCH(' \$1AWS/Lambda, FunctionName\$1 MetricName="Errors" ', 'Sum'))** retorna a soma da métrica `Errors` de todas as funções do Lambda.
O uso de linhas separadas para a expressão de pesquisa e a expressão matemática pode gerar resultados mais úteis. Por exemplo, suponha que você use as duas expressões a seguir em um gráfico. A primeira linha exibe linhas `Errors` separadas para cada uma das funções do Lambda. O ID dessa expressão é `e1`. A segunda linha adiciona outra linha que mostra a soma dos erros de todas as funções.
```
SEARCH(' {AWS/Lambda, FunctionName}, MetricName="Errors" ', 'Sum')
SUM(e1)
```