翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# OpenSearch パイプ処理言語 (PPL)
このセクションでは、OpenSearch PPL を使用した CloudWatch Logs のクエリの基本的な概要を示します。PPL を使用すると、パイプ集計コマンドを使用してデータを取得、クエリ、分析できるため、複雑なクエリの理解と作成が容易になります。この構文は Unix パイプに基づいており、コマンドを連鎖してデータの変換と処理を行えます。PPL を使用すると、データをフィルターして集計し、豊富な一連の算術、文字列、日付、条件付きなどの関数を用いて分析できます。
PPL クエリ`SOURCE`に を含めることは、 AWS CLI または API を使用してクエリを作成するときに、ロググループのフィールドインデックスと、クエリに含めるデータソースを指定するのに役立ちます。`SOURCE` コマンドは、CloudWatch コンソールではなく、 AWS CLI および API でのみサポートされます。CloudWatch コンソールを使用してクエリを開始するときは、コンソールインターフェイスを使用してロググループとデータソースの名前とタイプを指定します。
`aws:fieldIndex` を使用してインデックス付きデータのみを返すには、クエリで指定したフィールドでインデックス付けされたロググループのみをスキャンするようクエリに強制します。関連するロググループは、 `filterIndex` コマンドで指定されたフィールドに基づいて自動的に選択されます。これにより、クエリで指定された フィールドを含むログイベントを持たないロググループをスキップし、このフィールドインデックスのクエリで指定された値と一致するロググループのみをスキャンすることで、スキャンされたボリュームが減少します。`aws:fieldIndex` を使用して、ソースコマンドのフィールド名と値とともにフィールド名を指定し、指定されたフィールドと値を含むインデックス付きデータのみをクエリします。詳細については、[フィールドインデックスを作成してクエリパフォーマンスを改善し、スキャン量を削減する](CloudWatchLogs-Field-Indexing.md)を参照してください。
OpenSearch PPL は、標準ログクラスのロググループのクエリに使用できます。
**注記**
CloudWatch Logs でサポートされているすべての OpenSearch PPL クエリコマンドと構文や制限の詳細については、「OpenSearch Service デベロッパーガイド」の「[サポートされている PPL コマンド](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-ppl.html)」を参照してください。
使用できる他のクエリ言語については、「[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)」、「[CloudWatchMetrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)」を参照してください。
| コマンドまたは関数 | クエリの例 | 説明 |
| --- | --- | --- |
| `fields` | `fields field1, field2` | 射影が必要な一連のフィールドを表示します。 |
| `join` | `LEFT JOIN left=l, right=r on l.id = r.id `join_right_lg` \| fields l.field_1, r.field_2` | 2 つのデータセットを結合します。 |
| `where` | `where field1="success" \| where field2 != "i-023fe0a90929d8822" \| fields field3, field4, field5,field6 \| head 1000` | 指定した条件に基づいてデータをフィルタリングします。 |
| `aws:fieldIndex` | `source = [`aws:fieldIndex`="region", `region` = "us-west-2"] \| where status = 200 \| head 10` | クエリで指定したフィールドでインデックスが作成されたロググループのみをスキャンするようにクエリに強制することで、インデックス付きデータのみを返します。 |
| `stats` | `stats count(), count(field1), min(field1), max(field1), avg(field1) by field2 \| head 1000` | 集計と計算を実行します。 |
| `parse` | `parse field1 ".*/(?[^/]+$)" \| where field2 = "requestId" \| fields field1, field2 \| head 1000` | 文字列から正規表現 (regex) パターンを抽出し、抽出されたパターンを表示します。抽出されたパターンはその後、新しいフィールドの作成やデータのフィルタリングに使用できます。 |
| `sort` | `stats count(), count(field1), min(field1) as field1Alias, max(`field1`), avg(`field1`) by field2 \| sort -field1Alias \| head 1000` | 表示された結果をフィールド名で並べ替えます。 sort -FieldName を使用して降順で並べ替えます。 |
| `eval` | `eval field2 = field1 * 2 \| fields field1, field2 \| head 20` | フィールドの値を変更または処理し、別のフィールドに保存します。これは、列を数学的に変更したり、列に文字列関数を適用したり、列に日付関数を適用したりするのに有用です。 |
| `rename` | `rename field2 as field1 \| fields field1;` | 検索結果の 1 つ以上のフィールドの名前を変更します。 |
| `head` | `fields `@message` \| head 20` | 表示されるクエリ結果を最初の N 行に制限します。 |
| `top` | `top 2 field1 by field2` | フィールド内で最も頻度の高い値を抽出します。 |
| `dedup` | `dedup field1 \| fields field1, field2, field3` | 指定したフィールドに基づいて重複するエントリを削除します。 |
| `rare` | `rare field1 by field2` | フィールドリスト内のすべてのフィールドの最低頻度の値を検索します。 |
| `subquery` | `where field_1 IN [ search source= `subquery_lg` \| fields field_2 ] \| fields id, field_1 ` | PPL ステートメント内でネストされた複雑なクエリを実行します。 |
| `trendline` | `trendline sma(2, field1) as field1Alias` | フィールドの移動平均を計算します。 |
| `eventStats` | `eventstats sum(field1) by field2` | 計算された要約統計量を使用してイベントデータを補強します。イベント内の指定されたフィールドを分析し、さまざまな統計量を計算して、その結果を新しいフィールドとして各イベントに追加します。 |
| `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` | 複数の値を含むフィールドを別々の行に分割し、指定されたフィールドの値ごとに新しい行を作成します。 |
| `fillnull` | `fields `@timestamp`, error_code, status_code \| fillnull using status_code = "UNKNOWN", error_code = "UNKNOWN"` | null フィールドに指定した値を入力します。1 つ以上のフィールドで使用できます。 |
| `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) ` | フィールドをフラット化します。フィールドは `struct` または `array>` のタイプである必要があります。 |
| `cidrmatch` | `where cidrmatch(ip, '2003:db8::/32') \| fields ip ` | 指定された IP アドレスが指定された CIDR 範囲内にあるかどうかを確認します。 |
| `fieldsummary` | `where field1 != 200 \| fieldsummary includefields= field1 nulls=true` | 各フィールドの基本統計 (カウント、個別カウント、最小、最大、平均、stddev、平均) を計算します。 |
| `grok` | `grok email '.+@%{HOSTNAME:host}' \| fields email, host` | grok パターンでテキストフィールドを解析し、検索結果に結果を追加します。 |
| 文字列関数 | `eval field1Len = LENGTH(field1) \| fields field1Len` | PPL クエリ内の文字列およびテキストデータを操作および変換できる PPL の組み込み関数。例えば、大文字と小文字の変換、文字列の組み合わせ、パーツの抽出、テキストのクリーニングなどです。 |
| 日付および時刻関数 | `eval newDate = ADDDATE(DATE('2020-08-26'), 1) \| fields newDate ` | PPL クエリで日付とタイムスタンプデータを処理および変換するための組み込み関数。例えば、date\_add、date\_format、datediff、date-sub、timestampadd、timestampdiff、current\_timezone、utc\_timestamp、current\_date などです。 |
| 条件関数 | `eval field2 = isnull(field1) \| fields field2, field1, field3` | 特定のフィールド条件をチェックし、式を条件付きで評価する組み込み関数。例えば、field1 が null の場合、field2 を返します。 |
| 数学関数 | `eval field2 = ACOS(field1) \| fields field1` | PPL クエリで数学的計算と変換を実行するための組み込み関数。例えば、abs (絶対値）、round (四捨五入数値）、sqrt (平方根）、pow (出力計算）、ceil (最も近い整数に切り上げ) などです。 |
| 暗号化関数 | `eval crypto = MD5(field)\| head 1000` | 指定されたフィールドのハッシュを計算するには |
| JSON 関数 | `eval valid_json = json('[1,2,3,{"f1":1,"f2":[5,6]},4]') \| fields valid_json` | 配列、抽出、検証など、JSON を処理するための組み込み関数。例えば、json\_object、json\_array、to\_json\_string、json\_array\_length、json\_extract、json\_keys、json\_valid などです。 |
## クエリスコープ
クエリに SOURCE を含めることは、 AWS CLI または API を使用してクエリを作成するときに、クエリに含めるロググループを指定するのに役立ちます。SOURCE コマンドは、CloudWatch コンソールではなく、 AWS CLI および API でのみサポートされています。CloudWatch コンソールを使用してクエリを開始するときは、コンソールインターフェイスを使用してロググループとデータソースの名前とタイプを指定します。
PPL の source コマンドは、それらを指定する複数の方法をサポートするようになりました。
1. ロググループ
1. フィールドインデックス - 新規
1. データソースとタイプ - 新規
### ロググループ
ロググループのソース選択は、検索する必要がある正確なロググループ (複数可) がわかっている場合に使用できます。
```
source = [lg:`/aws/lambda/my-function`] | where status = 200 | head 10
```
### フィールドインデックス
フィールドインデックスベースのソース選択は、インデックスが作成されたフィールドをフィルターがターゲットにする場合、インデックスが付けられたデータのみに結果を制限することで、クエリされるデータの量を減らします。関連するロググループは、 `filterIndex` コマンドで指定されたフィールドに基づいて自動的に選択されます。フィールドインデックスとその作成方法の詳細については、「[Create field indexes to improve query performance and reduce scan volume](CloudWatchLogs-Field-Indexing.md)」を参照してください。
`aws:fieldIndex` を使用してインデックス付きデータのみを返すには、クエリで指定したフィールドでインデックス付けされたロググループのみをスキャンするようクエリに強制します。このフィールドでインデックス付けされるこれらのロググループの場合、インデックス付けされたフィールドのクエリで指定されたフィールドを含む任意のログイベントを持たないロググループをスキップすることで、クエリがさらに最適化されます。さらに、このフィールドインデックスのクエリで指定された値に一致するこれらのロググループのログイベントのみをスキャンしようとすることで、スキャンされるボリュームが減少します。フィールドインデックスとその作成方法の詳細については、「Create field indexes to improve query performance and reduce scan volume」を参照してください。
PPL では、 `aws:fieldIndex` を使用して、インデックスとして扱うキーと値のペアを指定します。構文は次のとおりです。
```
source = [`aws:fieldIndex`="region", `region` = "us-west-2"] | where status = 200 | head 10
```
次のとおりです。
1. ``aws:fieldIndex`="region"` はリージョンをフィールドインデックスとして識別します。
1. 注: = の代わりに、顧客は IN を使用して複数のインデックスを指定できます (以下の例)
1. ``region`="us-west-2"` は、適用するフィルター条件を識別します。
1. 注: = の代わりに、顧客は IN を使用して複数の値を指定できます (以下の例を参照)
お客様は次のように複数の fieldIndexes を指定できます。
```
source = [`aws:fieldIndex` IN ("status", "region"), `status` = 200, `region` IN ("us-west-2", "us-east-1")] | head 10
```
### データソースとタイプ
データソースとタイプベースのソース選択は、クエリが必要な正確なデータソースがわかっている場合に使用できます。このクエリは、指定されたデータソースとタイプを含む 1 つ以上のロググループで実行されます。
```
source = [ds:`data_source.type`] | where status = 200 | head 10
```
#### データソースクエリでサポートされる PPL
PPL でデータソースをクエリするためのユースケースをサポートするには、動的ソースセレクタ句を使用できます。この構文を使用して、検索コマンドでデータソースを指定することで、データソースをクエリできます。最大 10 個のデータソースを指定できます。
**[Syntax]** (構文)
```
source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`, ...ds:`DataSourcen.Typen`]
```
**クエリの例**
```
search source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`] | fields field1, field2
```
### 組み合わされた例
お客様はすべてのソース選択演算子を任意の順序で指定でき、結果は適用されるすべての条件の共通部分になります。
たとえば、/aws/lambda/my-function-1 には、さまざまなインデックスを含む複数のデータソースとタイプが含まれている場合があります。次のクエリが実行されると、返される結果にはソースイベントとタイプ DataSource1.Type1 のイベントのみが含まれ、'status' = 200 の基準に一致します。
```
search source=[
ds:`DataSource1.Type1`,
lg:`/aws/lambda/my-function-1`,
`aws:fieldIndex` IN ("status"), `status` = 200
]
```
## 制限事項
OpenSearch PPL を使用して CloudWatch Logs Insights でクエリを実行する場合、次の制限が適用されます。
+ データソースクエリでは、結合コマンドまたはサブクエリコマンドを使用できません。