# CloudWatch 検索式の構文
有効な検索式の形式は次のとおりです。
```
SEARCH(' {Namespace, DimensionName1, DimensionName2, ...} SearchTerm', 'Statistic')
```
次に例を示します。
```
SEARCH('{AWS/EC2,InstanceId} MetricName="CPUUtilization"', 'Average')
```
+ 検索語 `SEARCH` の後のクエリの最初の部分 (中括弧で囲まれている) は、検索される*メトリクススキーマ*です。メトリックスキーマには、メトリクス名前空間と 1 つ以上のディメンション名が含まれています。検索クエリにメトリクスキーマを含めることは、オプションです。指定した場合、メトリクスキーマには名前空間が含まれている必要があり、その名前空間で有効な 1 つ以上のディメンション名をオプションで含めることができます。
名前空間またはディメンション名にスペースまたは英数字以外の文字が含まれている場合を除き、メトリクスキーマ内で引用符を使用する必要はありません。その場合は、それらの文字を含む名前を二重引用符で囲む必要があります。
+ また、`SearchTerm` もオプションですが、有効な検索には、メトリクスキーマか `SearchTerm`、またはその両方を含める必要があります。`SearchTerm` には通常、アカウント ID、メトリクス名、またはディメンション値が 1 つまたは複数含まれます。`SearchTerm` には、部分一致および完全一致で検索する用語を複数含めることができます。ブール演算子を含めることもできます。
`SearchTerm` でアカウント ID を使用しても、CloudWatch クロスアカウントオブザーバビリティのモニターリングアカウントとして設定されているアカウントでのみ有効です。`SearchTerm` のアカウント ID の構文は `:aws.AccountId = 444455556666` です。`'LOCAL'` を使用して `:aws.AccountId = 'LOCAL'` のようにモニターリングアカウント自体を指定することもできます。
詳細については、「[CloudWatch のクロスアカウントオブザーバビリティ](CloudWatch-Unified-Cross-Account.md)」を参照してください。
`SearchTerm` には、1 つ以上の指定子 (この例の `MetricName=` など) を含めることができますが、指定子の使用は必須ではありません。
メトリクススキーマと `SearchTerm` は、単一引用符のペアで一緒に囲む必要があります。
+ `Statistic` は、有効な CloudWatch 統計の名前です。一重引用符で囲む必要があります。詳細については、「[統計](cloudwatch_concepts.md#Statistic)」を参照してください。
前の例では、ディメンション名として `AWS/EC2` を持つすべてのメトリクスについて `InstanceId` 名前空間を検索します。検出したすべての `CPUUtilization` メトリクスと、`Average` 統計を示すグラフを返します。
検索式で検索できるのは、過去 2 週間以内にデータを報告したメトリクスだけです。
**検索式の制限**
検索式の最大クエリサイズは 1,024 文字です。1 つのグラフに最大 100 つの検索式を含めることができます。グラフには最大 500 の時系列を表示できます。
## CloudWatch 検索式: トークン分割
`SearchTerm` を指定すると、検索機能で*トークン*が検索されます。トークンは、CloudWatch で、完全なメトリクス名、ディメンション名、ディメンション値、名前空間から自動的に生成される部分文字列です。CloudWatch により、元の文字列のキャメルケース文字で区別されたトークンが生成されます。数字は新しいトークンの開始部分として、英数字以外の文字は区切り文字として機能します。その結果、英数字以外の文字の前後にトークンが作成されます。
同じタイプのトークンの区切り文字の連続文字列は 1 つのトークンになります。
トークンはすべて小文字で生成されます。生成されたトークンの例を次の表に示します。
| 元の文字列 | 生成されたトークン |
| --- | --- |
| CustomCount1 | `customcount1`, `custom`, `count`, `1` |
| SDBFailure | `sdbfailure`, `sdb`, `failure` |
| Project2-trial333 | `project2trial333`, `project`, `2`, `trial`, `333` |
## CloudWatch 検索式: 部分一致
`SearchTerm` を指定すると、検索語もトークン分割されます。CloudWatch は、部分一致に基づいてメトリクスを検索します。部分一致は、検索語から生成された単一のトークンと、メトリクス名、名前空間、ディメンション名、またはディメンション値から生成された単一のトークンとの一致を表します。
単一のトークンに一致する部分一致検索では、大文字と小文字は区別されません。たとえば、次のいずれかの検索語を使用して `CustomCount1` メトリクスを返すことができます。
+ `count`
+ `Count`
+ `COUNT`
ただし、検索語 `couNT` は、`cou` と `NT` にトークン分割されるため、検索語に `couNT` を使用しても、`CustomCount1` は見つかりません。
元の名前に連続して現れる複数のトークンである複合トークンにも一致するように検索することもできます。複合トークンと一致させるには、大文字と小文字を区別して検索します。たとえば、元の語が `CustomCount1` で、`CustomCount` や `Count1` と検索すると一致しますが、`customcount` や `count1` では一致しません。
## CloudWatch 検索式: 完全一致
完全一致を必要とする検索語の部分を二重引用符で囲むことで、検索語の完全一致のみを検索するように検索を定義することができます。これらの二重引用符は、検索語全体で使用される単一引用符で囲まれています。たとえば、`CustomCount1` が `MyNamespace` という名前の名前空間にメトリクス名、ディメンション名、ディメンション値として存在する場合は、**SEARCH(' \$1MyNamespace\$1, "CustomCount1" ', 'Maximum')** で正確な文字列が検索されます。ただし、**SEARCH(' \$1MyNamespace\$1, "customcount1" ', 'Maximum')** または **SEARCH(' \$1MyNamespace\$1, "Custom" ', 'Maximum')** と検索した場合、この文字列は見つかりません。
部分一致の語と完全一致の語を単一の検索式に組み合わせることができます。例えば、**SEARCH(' \$1AWS/NetworkELB, LoadBalancer\$1 "ConsumedLCUs" OR flow ', 'Maximum')** では、`ConsumedLCUs` という名前の Elastic Load Balancing メトリクスと、トークン `flow` を含むすべての Elastic Load Balancing メトリクスまたはディメンションが返されます。
次の例のように、英数字以外の文字やスペースなどの特殊文字を含む名前を見つけるには、完全一致を使用することもお勧めします。
```
SEARCH(' {"My Namespace", "Dimension@Name"}, "Custom:Name[Special_Characters" ', 'Maximum')
```
## CloudWatch 検索式: メトリクススキーマの除外
これまでに示した例にはすべて、中括弧で囲まれたメトリクスキーマが含まれています。スキーマメトリクスを省略する検索も有効です。
たとえば、**SEARCH(' "CPUUtilization" ', 'Average')** では、文字列 `CPUUtilization` の完全一致であるメトリクス名、ディメンション名、ディメンション値、名前空間がすべて返ります。AWS のメトリクス名前空間では、これには Amazon EC2、Amazon ECS、SageMaker AI などの複数のサービスのメトリクスを入れることができます。
この検索を 1 つの AWS サービスに絞り込むには、ベストプラクティスとして、メトリクススキーマの名前空間と必要なディメンションを指定することをお勧めします。以下に例を示します。この場合、検索は `AWS/EC2` 名前空間に絞り込まれているため、そのようなメトリクスのディメンション値として `CPUUtilization` を定義した場合は、他のメトリクスの結果が返ります。
```
SEARCH(' {AWS/EC2, InstanceType} "CPUUtilization" ', 'Average')
```
または、以下の例のように、`SearchTerm` に名前空間を追加することもできます。ただし、この例では、カスタムのディメンション名または値であっても、`AWS/EC2` に一致します。
```
SEARCH(' "AWS/EC2" MetricName="CPUUtilization" ', 'Average')
```
## CloudWatch 検索式: 検索でプロパティ名を指定する
以下の `"CustomCount1"` の完全一致検索では、その名称と正確に一致するすべてのメトリクスが返ります。
```
SEARCH(' "CustomCount1" ', 'Maximum')
```
ただし、`CustomCount1` のディメンション名、ディメンション値、または名前空間のメトリクスも返ります。検索をさらに構造化するには、検索で見つけるオブジェクトのタイプのプロパティ名を指定します。次の例では、すべての名前空間を検索し、`CustomCount1` という名前のメトリクスが返ります。
```
SEARCH(' MetricName="CustomCount1" ', 'Maximum')
```
また、名前空間とディメンション名/値をプロパティ名として使用することもできます。以下に例を示します。これらの例のうち、1 つ目は、部分一致検索でもプロパティ名を使用できることを示しています。
```
SEARCH(' InstanceType=micro ', 'Average')
```
```
SEARCH(' InstanceType="t2.micro" Namespace="AWS/EC2" ', 'Average')
```
## CloudWatch 検索式: 英数字以外の文字
英数字以外の文字は区切り文字として機能し、メトリクスの名前、ディメンション、名前空間、および検索語をトークンに分割する場所を示します。語がトークン分割されると、英数字以外の文字は取り除かれ、トークンには表示されません。たとえば、`Network-Errors_2` では、トークン `network`、`errors`、および `2` が生成されます。
検索語には、英数字以外の文字を含めることができます。これらの文字が検索語に含まれている場合は、部分一致で複合トークンを指定できます。たとえば、次の検索ではすべて、`Network-Errors-2` または `NetworkErrors2` という名前のメトリクスが見つかります。
```
network/errors
network+errors
network-errors
Network_Errors
```
完全な値で検索を行う場合、完全一致検索で使用される英数字以外の文字は、検索対象の文字列に含まれる正しい文字である必要があります。たとえば、`Network-Errors-2` を検索する場合、`"Network-Errors-2"` と検索すると一致しますが、`"Network_Errors_2"` では一致しません。
完全一致検索を行う場合、以下の文字はバックスラッシュを使ってエスケープする必要があります。
```
" \ ( )
```
たとえば、完全一致でメトリクス名 `Europe\France Traffic(Network)` を検索するには、検索語に **"Europe\$1\$1France Traffic\$1(Network\$1)"** を使用します。
## CloudWatch 検索式: ブール演算子
ブール演算子 `AND`、`OR`、`NOT` を `SearchTerm` 内で使用して検索することができます。ブール演算子は、検索語全体を囲むために使用する単一引用符で囲まれています。ブール演算子では、大文字と小文字は区別されるため、`and`、`or`、および `not` はブール演算子として有効ではありません。
`AND` を検索で明示的に使用することができます。たとえば、**SEARCH('\$1AWS/EC2,InstanceId\$1 network AND packets', 'Average')** のように使用します。`AND` 演算子がない場合、検索語間にブール値を使用しないと明示的に検索されないため、**SEARCH(' \$1AWS/EC2,InstanceId\$1 network packets ', 'Average')** では、同じ検索結果が得られます。
検索結果からデータのサブセットを除外するには `NOT` を使用します。たとえば、**SEARCH(' \$1AWS/EC2,InstanceId\$1 MetricName="CPUUtilization" NOT i-1234567890123456 ', 'Average')** では、すべてのインスタンスの `CPUUtilization` が返ります (インスタンス `i-1234567890123456` は除く)。また、唯一の検索語として、`NOT` を使用することもできます。たとえば、**SEARCH( 'NOT Namespace=AWS ', 'Maximum')** では、すべてのカスタムメトリクス (`AWS` を含まない名前空間を含むメトリクス) が得られます。
クエリでは、複数の `NOT` 句を使用できます。たとえば、**SEARCH(' \$1AWS/EC2,InstanceId\$1 MetricName="CPUUtilization" NOT "ProjectA" NOT "ProjectB" ', 'Average')** では、リージョン内のすべてのインスタンスの `CPUUtilization` が返ります (ただし、ディメンション値 `ProjectA` または `ProjectB` が含まれるものは除く)。
強力で詳細な検索を行うには、ブール演算子を組み合わせることができます。以下に例を示します。演算子をグループ化するには括弧を使用します。
次の 2 つの例ではいずれも、EC2 と EBS 名前空間から、`ReadOps` を含むメトリクス名がすべて返ります。
```
SEARCH(' (EC2 OR EBS) AND MetricName=ReadOps ', 'Maximum')
```
```
SEARCH(' (EC2 OR EBS) MetricName=ReadOps ', 'Maximum')
```
次の例では、前の検索は、`ProjectA` を含む結果のみに絞り込まれます。その結果、ディメンションの値になります。
```
SEARCH(' (EC2 OR EBS) AND ReadOps AND ProjectA ', 'Maximum')
```
次の例では、ネストされたグループ化を使用します。すべての関数からの `Errors` の Lambda メトリクスと、`ProjectA` または `ProjectB` を含む名前の関数の `Invocations` を返します。
```
SEARCH(' {AWS/Lambda,FunctionName} MetricName="Errors" OR (MetricName="Invocations" AND (ProjectA OR ProjectB)) ', 'Average')
```
## CloudWatch 検索式: 数式の使用
検索式は、グラフ内の数式で使用できます。
例えば、**SUM(SEARCH(' \$1AWS/Lambda, FunctionName\$1 MetricName="Errors" ', 'Sum'))** は、すべての Lambda 関数の `Errors` メトリクスの合計を返します。
検索式と数式に個別の行を使用すると、より有用な結果が得られる場合があります。たとえば、グラフで次の 2 つの式を使用するとします。最初の行には、各 Lambda 関数の各 `Errors` 行が表示されます。この数式の ID は、`e1` です。2 行目には、すべての関数からのエラーの合計を示す別の行が追加されています。
```
SEARCH(' {AWS/Lambda, FunctionName}, MetricName="Errors" ', 'Sum')
SUM(e1)
```