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á.
# OpenSearch Linguagem de processamento canalizado (PPL)
Esta seção contém uma introdução básica à consulta de CloudWatch registros usando OpenSearch PPL. Com a PPL, você pode recuperar, consultar e analisar dados usando comandos agrupados, facilitando a compreensão e a composição de consultas complexas. Sua sintaxe é baseada em pipes Unix e permite o encadeamento de comandos para transformar e processar dados. Com a PPL, você pode filtrar e agregar dados e usar um amplo conjunto de funções matemáticas, de sequências de caracteres, de data, condicionais e outras para análise.
Incluir `SOURCE` em uma consulta PPL é uma forma útil de especificar os grupos de registros, os índices de campo e as fontes de dados a serem incluídos em uma consulta quando você estiver usando a API AWS CLI ou para criar uma consulta. O `SOURCE` comando é suportado somente na API AWS CLI and, não no CloudWatch console. Ao usar o CloudWatch console para iniciar uma consulta, você usa a interface do console para especificar os grupos de log e o nome e o tipo da fonte de dados.
Use `aws:fieldIndex` para retornar somente dados indexados, forçando uma consulta a verificar somente grupos de logs indexados em um campo especificado na consulta. Os grupos de registros relevantes são selecionados automaticamente, com base nos campos especificados no `filterIndex` comando. Isso reduz o volume escaneado ignorando grupos de registros que não têm nenhum evento de registro contendo o campo especificado na consulta e somente grupos de registros de varredura que correspondam ao valor especificado na consulta para esse índice de campo. Use `aws:fieldIndex` para especificar o nome do campo, junto com o nome e o valor do campo no comando de origem para consultar somente dados indexados contendo o campo e o valor especificados. Para obter mais informações, consulte [Crie índices de campo para melhorar o desempenho da consulta e reduzir o volume de escaneamento](CloudWatchLogs-Field-Indexing.md).
Você pode usar o OpenSearch PPL para consultas de grupos de registros na Classe de Registro Padrão.
**nota**
Para obter informações sobre todos os comandos de consulta OpenSearch PPL compatíveis com CloudWatch os registros e informações detalhadas sobre sintaxe e restrições, consulte [Comandos PPL compatíveis](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-ppl.html) no OpenSearch Service Developer Guide.
Para obter informações sobre outras linguagens de consulta que você pode usar, consulte [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html), [OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html) e [CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)
| Comando ou função | Consulta de exemplo | Description |
| --- | --- | --- |
| `fields` | `fields field1, field2` | Exibe um conjunto de campos que precisam de projeção. |
| `join` | `LEFT JOIN left=l, right=r on l.id = r.id `join_right_lg` \| fields l.field_1, r.field_2` | Une dois conjuntos de dados. |
| `where` | `where field1="success" \| where field2 != "i-023fe0a90929d8822" \| fields field3, field4, field5,field6 \| head 1000` | Filtra os dados com base nas condições que você especifica. |
| `aws:fieldIndex` | `source = [`aws:fieldIndex`="region", `region` = "us-west-2"] \| where status = 200 \| head 10` | Retorna somente dados indexados, forçando uma consulta a examinar somente grupos de registros que estão indexados em um campo que você especifica na consulta. |
| `stats` | `stats count(), count(field1), min(field1), max(field1), avg(field1) by field2 \| head 1000` | Executa agregações e cálculos |
| `parse` | `parse field1 ".*/(?[^/]+$)" \| where field2 = "requestId" \| fields field1, field2 \| head 1000` | Extrai um padrão de expressão regular (regex) de uma string e exibe o padrão extraído. O padrão extraído pode ser usado posteriormente para criar novos campos ou filtrar dados. |
| `sort` | `stats count(), count(field1), min(field1) as field1Alias, max(`field1`), avg(`field1`) by field2 \| sort -field1Alias \| head 1000` | Classifique os resultados exibidos por um nome de campo. Use classificar - FieldName para classificar em ordem decrescente. |
| `eval` | `eval field2 = field1 * 2 \| fields field1, field2 \| head 20` | Modifica ou processa o valor de um campo e o armazena em outro campo. Esse comando é útil para modificar matematicamente uma coluna, aplicar funções de string a uma coluna ou aplicar funções de data a uma coluna. |
| `rename` | `rename field2 as field1 \| fields field1;` | Renomeia um ou mais campos no resultado da pesquisa. |
| `head` | `fields `@message` \| head 20` | Limita os resultados da consulta exibidos às primeiras N linhas. |
| `top` | `top 2 field1 by field2` | Encontra os valores mais frequentes para um campo. |
| `dedup` | `dedup field1 \| fields field1, field2, field3` | Remove entradas duplicadas com base nos campos que você especifica. |
| `rare` | `rare field1 by field2` | Encontra os valores menos frequentes de todos os campos na lista de campos. |
| `subquery` | `where field_1 IN [ search source= `subquery_lg` \| fields field_2 ] \| fields id, field_1 ` | Executa consultas complexas e aninhadas em suas instruções de PPL. |
| `trendline` | `trendline sma(2, field1) as field1Alias` | Calcula as médias móveis dos campos. |
| `eventStats` | `eventstats sum(field1) by field2` | Enriquece os dados de evento com estatísticas resumidas calculadas. Esse comando analisa campos especificados em seus eventos, calcula várias medidas estatísticas e, em seguida, anexa esses resultados a cada evento original como novos campos. |
| `expand` | `eval tags_array_string = json_extract(`@message`, '$.tags')\| eval tags_array = json_array(json_extract(tags_string, '$[0]'), json_extract(tags_string, '$[1]'))\| expand tags_array as color_tags` | Divide um campo contendo vários valores em linhas separadas, criando uma nova linha para cada valor no campo especificado. |
| `fillnull` | `fields `@timestamp`, error_code, status_code \| fillnull using status_code = "UNKNOWN", error_code = "UNKNOWN"` | Preenche campos nulo com o valor que você fornece. Pode ser usado em um ou mais campos. |
| `flatten` | `eval metadata_struct = json_object('size', json_extract(metadata_string, '$.size'), 'color', json_extract(metadata_string, '$.color')) \| flatten metadata_struct as (meta_size, meta_color) ` | Nivela um campo. O campo deve ser do tipo: `struct` ou `array>`. |
| `cidrmatch` | `where cidrmatch(ip, '2003:db8::/32') \| fields ip ` | Verifica se o endereço IP especificado está dentro do intervalo CIDR especificado. |
| `fieldsummary` | `where field1 != 200 \| fieldsummary includefields= field1 nulls=true` | Calcula estatísticas básicas para cada campo (contagem, contagem distinta, mín, máx, méd., stddev e mediana). |
| `grok` | `grok email '.+@%{HOSTNAME:host}' \| fields email, host` | Analisa um campo de texto com um padrão Grok e anexa os resultados ao resultado da pesquisa. |
| Funções de string | `eval field1Len = LENGTH(field1) \| fields field1Len` | Funções integradas na PPL que podem manipular e transformar dados de string e texto em consultas PPL. Por exemplo, converter maiúsculas e minúsculas, combinar strings, extrair partes e apagar texto. |
| Funções de data e hora | `eval newDate = ADDDATE(DATE('2020-08-26'), 1) \| fields newDate ` | Funções integradas para manipular e transformar dados de data e carimbo de data/hora em consultas PPL. Por exemplo: date\_add, date\_format, datediff, date-sub, timestampadd, timestampdiff, current\_timezone, utc\_timestamp, e current\_date. |
| Funções de condição | `eval field2 = isnull(field1) \| fields field2, field1, field3` | Funções integradas que verificam condições de campo específicas e avaliam expressões condicionalmente. Por exemplo, se campo1 for nulo, retorne campo2. |
| Funções matemáticas | `eval field2 = ACOS(field1) \| fields field1` | Funções integradas para realizar cálculos matemáticos e transformações em consultas PPL. Por exemplo: abs (valor absoluto), round (arredonda números), sqrt (raiz quadrada), pow (cálculo de potência) e ceil (arredonda até o número inteiro mais próximo). |
| CryptoGraphic funções | `eval crypto = MD5(field)\| head 1000` | Para calcular o hash de um determinado campo |
| Funções JSON | `eval valid_json = json('[1,2,3,{"f1":1,"f2":[5,6]},4]') \| fields valid_json` | Funções integradas para manipular JSON, incluindo matrizes, extração e validação. Por exemplo: json\_object, json\_array, to\_json\_string, json\_array\_length, json\_extract, json\_keys e json\_valid. |
## Escopo da consulta
Incluir SOURCE em uma consulta é uma forma útil de especificar os grupos de registros a serem incluídos em uma consulta quando você estiver usando a API AWS CLI ou para criar uma consulta. O comando SOURCE é suportado somente na API AWS CLI e, não no CloudWatch console. Ao usar o CloudWatch console para iniciar uma consulta, você usa a interface do console para especificar os grupos de log e o nome e o tipo da fonte de dados.
O comando source do PPL agora oferece suporte a várias maneiras de especificá-los:
1. Grupo de registros
1. Índices de campo - Novo
1. Fonte e tipo de dados - Novo
### Grupo de logs
A seleção da fonte do grupo de registros pode ser usada quando os clientes sabem quais grupos de registros exatos precisam ser pesquisados
```
source = [lg:`/aws/lambda/my-function`] | where status = 200 | head 10
```
### Índices de campo
A seleção da fonte com base no índice de campo reduz a quantidade de dados consultados ao limitar os resultados somente aos dados indexados quando seus filtros segmentam campos que foram indexados. Os grupos de registros relevantes são selecionados automaticamente, com base nos campos especificados no `filterIndex` comando. Para obter mais informações sobre índices de campo e como criá-los, consulte [Criar índices de campo para melhorar o desempenho da consulta e reduzir o volume de varredura](CloudWatchLogs-Field-Indexing.md).
Use `aws:fieldIndex` para retornar somente dados indexados, forçando uma consulta a verificar somente grupos de logs indexados em um campo especificado na consulta. Para esses grupos de logs indexados nesse campo, ele otimiza ainda mais a consulta ignorando os grupos que não têm nenhum evento de logs contendo o campo especificado na consulta do campo indexado. Isso reduz ainda mais o volume escaneado ao tentar verificar somente eventos de logs desses grupos que correspondam ao valor especificado na consulta para esse índice de campo. Para obter mais informações sobre índices de campo e como criá-los, consulte Criar índices de campo para melhorar o desempenho da consulta e reduzir o volume de varredura.
Em PPL, `aws:fieldIndex` é usado para especificar quais pares de valores-chave devem ser tratados como índices. A sintaxe é a seguinte
```
source = [`aws:fieldIndex`="region", `region` = "us-west-2"] | where status = 200 | head 10
```
em que,
1. ``aws:fieldIndex`="region"`identifica a região como índice de campo.
1. Observação: em vez de =, os clientes podem usar IN para especificar vários índices (exemplo abaixo)
1. ``region`="us-west-2"`identifica a condição do filtro a ser aplicada
1. Observação: em vez de =, os clientes podem usar IN para especificar vários valores (exemplo abaixo)
Os clientes podem especificar vários índices de campo da seguinte forma
```
source = [`aws:fieldIndex` IN ("status", "region"), `status` = 200, `region` IN ("us-west-2", "us-east-1")] | head 10
```
### Fonte e tipo de dados
A seleção da fonte de dados e da fonte baseada no tipo pode ser usada quando os clientes sabem quais fontes de dados exatas precisam ser consultadas. Essa consulta é executada em um ou mais grupos de registros que contêm a fonte e o tipo de dados especificados.
```
source = [ds:`data_source.type`] | where status = 200 | head 10
```
#### PPL compatível para consultas de fontes de dados
Para oferecer suporte ao caso de uso da consulta de fontes de dados no PPL, você pode usar a cláusula seletora dinâmica de origem. Usando essa sintaxe, você pode consultar fontes de dados especificando-as no comando search. Você pode especificar até 10 fontes de dados.
**Sintaxe**
```
source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`, ...ds:`DataSourcen.Typen`]
```
**Consulta de exemplo**
```
search source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`] | fields field1, field2
```
### Exemplo de combinação
Os clientes podem especificar todos os operadores de seleção de origem em qualquer ordem e os resultados seriam a interseção de todas as condições aplicadas.
Por exemplo,/aws/lambda/my-function-1 pode conter várias fontes e tipos de dados, incluindo uma grande variedade de índices. Quando a consulta a seguir for executada, os resultados retornados terão apenas eventos de origem e tipo DataSource 1.Type1 e corresponderão aos critérios de 'status' = 200.
```
search source=[
ds:`DataSource1.Type1`,
lg:`/aws/lambda/my-function-1`,
`aws:fieldIndex` IN ("status"), `status` = 200
]
```
## Restrições
As restrições a seguir se aplicam quando você usa o OpenSearch PPL para fazer consultas no CloudWatch Logs Insights.
+ Você não pode usar comandos de junção ou subconsulta com consultas de fonte de dados.