# CloudWatch Metrics Insights のクエリコンポーネントと構文
CloudWatch Metrics Insights の構文は以下のとおりです。
```
SELECT {{FUNCTION}}({{metricName}})
FROM {{namespace}} | SCHEMA(...)
[ WHERE {{labelKey}} OPERATOR {{labelValue}} [AND ... ] ]
[ GROUP BY {{labelKey}} [ , ... ] ]
[ ORDER BY {{FUNCTION}}() [ DESC | ASC ] ]
[ LIMIT {{number}} ]
```
Metrics Insights のクエリで使用可能な句は以下のとおりです。キーワードでは大文字と小文字は区別されませんが、メトリクスの名前、名前空間、ディメンションなど、メトリクスの識別子については大文字と小文字が区別されます。
**SELECT**
必須。各タイムバケットの (指定された期間によって決定される) 観測値を集計するための関数を指定します。同時に、クエリするメトリクスの名前も指定します。
**FUNCTION** での有効な値は、`AVG`、`COUNT`、`MAX`、`MIN`、および `SUM` です。
+ `AVG` では、クエリで一致があった観測値の平均を計算します。
+ `COUNT` では、クエリで一致した観測値のカウントを返します。
+ `MAX` では、クエリで一致があった観測値の最大値を返します。
+ `MIN` では、クエリで一致があった観測値の最小値を返します。
+ `SUM` では、クエリで一致があった観測値を合計し、その値を返します。
**FROM**
必須。メトリクスのソースを指定します。クエリされるメトリクスを含むメトリクス名前空間、あるいは、**SCHEMA** テーブル関数のどちらかを指定します。メトリクス名前空間の例としては、`"AWS/EC2"`、`"AWS/Lambda"` などを初めとして、カスタムメトリクス用にユーザーが作成したメトリクス名前空間なども含まれます。
**/** を含む (または、文字、数字、アンダースコア以外の文字を含む) メトリクス名前空間は、二重引用符で囲む必要があります。詳細については、「[引用符やエスケープ文字を使用すべき場合を教えてください。](#cloudwatch-metrics-insights-syntaxdetails)」を参照してください。
**SCHEMA**
**FROM** 句内で使用できるオプションのテーブル関数。**SCHEMA** は、クエリ結果をリストされたディメンションと完全に一致したメトリクスからのもの、あるいは、ディメンションを持たないメトリクスからのものに絞り込みます。
**SCHEMA** 句を使用する際は、クエリ対象のメトリクス名前空間を指定するために、(最初の引数として) 少なくとも 1 つを渡す必要があります。**SCHEMA** において、この名前空間引数のみを指定した場合は、クエリ結果の範囲がディメンションを持たないメトリクスのみに絞られます。
**SCHEMA** で、名前空間引数の後に他の引数を指定する場合、それらの追加の引数は*ラベル*キーにする必要があります。ラベルキーでは、ディメンション名を指定します。このラベルキーを 1 つ以上指定することで、ディメンションセットが正確に一致するメトリクスのみに、クエリ結果の範囲が絞り込まれます。これらのラベルキーの順序は任意です。
例:
+ **SELECT AVG(CPUUtilization) FROM "AWS/EC2"** は、`AWS/EC2` 名前空間内にあるすべての `CPUUtilization` メトリクスと一致し、ディメンションは関係ありません。結果には、単一の集計時系列が返されます。
+ **SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2")** では、`AWS/EC2` 名前空間内でディメンションが定義されていない `CPUUtilization` メトリクスのみが一致します。
+ **SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId)** では、厳密に 1 つのディメンション (`InstanceId`) で CloudWatch に報告された `CPUUtilization` メトリクスのみと一致します。
+ **SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)** では、厳密に 2 つのディメンション (`LoadBalancer` と `AvailabilityZone`) で `AWS/ApplicationELB` から CloudWatch に報告された `RequestCount` メトリクスのみと一致します。
**WHERE**
オプション。1 つ以上のラベルキーで特定のラベル値を使用しながら指定した式と一致するメトリクスのみに、結果をフィルタリングします。例えば、**WHERE InstanceType = 'c3.4xlarge'** は、結果を `c3.4xlarge` インスタンスタイプのみにフィルタリングします。また、**WHERE InstanceType \!= 'c3.4xlarge'**では、`c3.4xlarge` を除くすべてのインスタンスタイプに結果をフィルタリングします。
モニタリングアカウントでクエリを実行する場合、`WHERE AWS.AccountId` を使用して、指定したアカウントのみに結果を制限できます。例えば、`WHERE AWS.AccountId=444455556666` は `444455556666` アカウントのみのメトリクスをクエリします。クエリをモニタリングアカウント自体のメトリクスにのみ制限するには、`WHERE AWS.AccountId=CURRENT_ACCOUNT_ID()` を使用します。
ラベル値は、常に一重引用符で囲む必要があります。
**WHERE 句でのタグの使用**
構文 `tag.keyName` を使用して、AWS リソースタグで結果をフィルタリングできます。タグフィルターは、ディメンションフィルターと同じ演算子ルールに従います。例えば、次のようになります。
+ WHERE `tag.env = 'prod'` と記述すると、*env=prod* でタグ付けされたリソースからメトリクスをフィルタリングします。
+ WHERE `tag.department != 'test'` と記述すると、*department=test* でタグ付けされたリソースからメトリクスを除外します。
タグフィルターはディメンションフィルターと組み合わせることができます。
`WHERE tag.env = 'prod' AND InstanceType = 'm5.large'`
**サポートされている演算子**
**WHERE** 句では以下の演算子がサポートされます。
+ **=** ラベル値は指定された文字列と一致することを表します。
+ **\!=**ラベル値は、指定した文字列と一致しないことを表します。
+ **AND** は、指定された 2 つの条件がともに true である場合に一致することを表します。**AND** キーワードは、2 つ以上の条件を指定するために使用することもできます。
**グループ化の条件**
オプション。クエリ結果を複数の時系列にグループ化します。各時系列は、指定したラベルキーもしくは他のキーでの、さまざまな値に対応します。例えば `GROUP BY InstanceId` を使用すると、`InstanceId` の各値に応じて異なる時系列が返されます。`GROUP BY ServiceName, Operation` を使用すると、`ServiceName` と `Operation` の値による可能な組み合わせごとに、それぞれ時系列が作成されます。
**GROUP BY** 句では、デフォルトで、結果がアルファベットの昇順に並べられます。その際は、この **GROUP BY** 句で指定されたラベルシーケンスが使用されます。この結果の順序を変更するには、クエリに **ORDER BY** 句を追加します。
モニタリングアカウントでクエリを実行する場合、`GROUP BY AWS.AccountId` を使用して、各結果をその生成元のアカウントに基づいてグループ化できます。
**GROUP BY 句でのタグの使用**
構文 `tag.keyName` を使用して、AWS リソースタグ値で結果をグループ化できます。例えば、次のようになります。
+ *GROUP BY tag.environment* と記述すると、環境タグ値ごとに個別の時系列を作成します。
+ *GROUP BY tag.team, InstanceType* と記述すると、タグ値とディメンション値の両方でグループ化します。
+ *GROUP BY tag.team, AWS.AccountId* と記述すると、タグとリンクされたソース AccountID の両方でグループ化します。
一致するメトリクスの一部に、**GROUP BY** 句で指定された特定のラベルキーを含まないものがある場合、`Other` という名前の NULL グループが返されます。例えば、`GROUP BY ServiceName, Operation` を指定している場合で、返されたメトリクスの一部にディメンションとして `ServiceName` を含まないものがあると、これらのメトリクスは、`Other` という値の `ServiceName` を持つものとして表示されます。
**ORDER BY**
オプション。クエリが複数の時系列を返す場合に、それら返される時系列で使用する順序を指定します。この順序は、**[ORDER BY]** 句で指定した **[FUNCTION]** が検出した値に基づいて決定されます。**FUNCTION** は、返されたそれぞれの時系列から単一のスカラー値を算出し、この値が、順序を決定するために使用されます。
また順序には、**ASC** (昇順) か **DESC** (降順) のどちらを使用するかも指定します。この指定を省略した場合は、デフォルトで昇順の **ASC** が使用されます。
例えば `ORDER BY MAX() DESC` 句では、対象の時間範囲内での観測結果を、最大データポイントにより降順で順序付けします。つまり、最大データポイントが最も多い時系列が、最初の結果として返されます。
**ORDER BY** 句内で使用可能な関数は、`AVG()`、`COUNT()`、`MAX()`、`MIN()`、および `SUM()` です。
**ORDER BY** 句を **LIMIT** 句とともに使用した場合、返される結果は「Top N」クエリになります。個別のクエリが返すことができる時系列は 500 個以下であるため、**ORDER BY** は、クエリから多数のメトリクスを返させたい場合にも役立ちます。クエリで 500 個を超える時系列 が一致した場合に **ORDER BY** 句を使用していると、時系列が並べ替えられ、その順序内で最初の 500 個までの時系列を結果として返すことができます。
**LIMIT**
オプション。クエリによって返される時系列の数を、指定した値に制限します。指定できる最大値は 500 です。また、クエリに **LIMIT** を指定しない場合でも、返すことができる時系列は 500 個以下です。
**LIMIT** 句を **ORDER BY** 句とともに使用すると、「Top N」のクエリが返されます。
## 引用符やエスケープ文字を使用すべき場合を教えてください。
クエリで指定するラベル値は、常に一重引用符で囲む必要があります。例えば、**SELECT MAX(CPUUtilization) FROM "AWS/EC2" WHERE AutoScalingGroupName = 'my-production-fleet'** のようにします。
文字、数字、アンダースコア (\_) 以外の文字を含むメトリクスの名前空間、メトリクス名、ラベルキーは、二重引用符で囲む必要があります。例としては、**SELECT MAX("My.Metric")** のようになります。
これらのいずれかに二重引用符または一重引用符自体が含まれている (例: `Bytes"Input"`) 場合は、**SELECT AVG("Bytes\\"Input\\"")** のようにして、各引用符をバックスラッシュでエスケープする必要があります。
メトリクス名前空間、メトリクス名、またはラベルキーに、Metrics Insights での予約キーワードが含まれている場合は、これらも二重引用符で囲む必要があります。例えば、`LIMIT` という名前のメトリクスを指定するのであれば、`SELECT AVG("LIMIT")` のようになります。また、予約キーワードを含まない場合に、名前空間、メトリクス名、またはラベルを二重引用符で囲んだとしても、エラーとはなりません。
全予約キーワードの一覧については、「[予約済みキーワード](cloudwatch-metrics-insights-reserved-keywords.md)」を参照してください。
## リッチクエリの作成手順
このセクションでは、利用可能なすべての句を使用してクエリを作成する際の完全な例を、ステップバイステップで解説します。
まず次のクエリから始めます。このクエリは、`LoadBalancer` と `AvailabilityZone` の両方のディメンションで収集された、Application Load Balancer のすべての `RequestCount` メトリクスを集計します。
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
```
特定のロードバランサーからのメトリクスのみを表示するには、**WHERE** 句を追加します。これにより、返されるメトリクスを `LoadBalancer` ディメンションの値が `app/load-balancer-1` であるもののみに制限できます。
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
```
前述のクエリでは、このロードバランサーに関するすべてのアベイラビリティーゾーンからの `RequestCount` メトリクスが、1 つの時系列内に集計されます。アベイラビリティーゾーンごとに異なる時系列を表示したい場合は、**GROUP BY** 句を追加します。
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
```
次に、結果を並べ替えて、最高値を最初に表示するようにできます。以下の **ORDER BY** 句では、クエリの一定時間範囲内にある各時系列によって報告された最大値について、対応する時系列が降順で順序付けられます。
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
ORDER BY MAX() DESC
```
タグを使用して結果をさらにフィルタリングすることもできます。例えば、特定の環境でタグ付けされたロードバランサーの結果のみを表示する場合は、WHERE 句にタグフィルタリングを次のように追加できます。
```
SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone) WHERE LoadBalancer = 'app/load-balancer-1' AND tag.Environment = 'prod' GROUP BY AvailabilityZone ORDER BY MAX() DESC
```
ディメンションの代わりに (またはディメンションに追加して) タグ値で結果をグループ化することもできます。例えば、Application タグでのグループ化は次のようになります。
```
SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone) WHERE tag.Environment = 'prod' GROUP BY tag.Application ORDER BY MAX() DESC
```
さらに、主として「Top N」タイプのクエリを表示したい場合には、**LIMIT** 句を使用します。この最後の例では、`MAX` 値が最上位の 5 つに入っている時系列のみに結果を制限しています。
```
SELECT SUM(RequestCount)
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
ORDER BY MAX() DESC
LIMIT 5
```
## クロスアカウントクエリの例
こうした例は、CloudWatch クロスアカウントオブザーバビリティにモニタリングアカウントとして設定されたアカウントで実行する場合に有効です。
次の例では、ソースアカウント 123456789012 内の Amazon EC2 インスタンスをすべて検索して、その平均を返しています。
```
SELECT AVG(CpuUtilization)
FROM "AWS/EC2"
WHERE AWS.AccountId ='123456789012'
```
次の例では、リンクされたすべてのソースアカウント内の `AWS/EC2` で `CPUUtilization` メトリクスをクエリし、アカウント ID とインスタンスタイプで結果をグループ化しています。
```
SELECT AVG(CpuUtilization)
FROM "AWS/EC2"
GROUP BY AWS.AccountId, InstanceType
```
次の例では、モニタリングアカウント自体で `CPUUtilization` をクエリしています。
```
SELECT AVG(CpuUtilization)
FROM "AWS/EC2"
WHERE AWS.AccountId = CURRENT_ACCOUNT_ID()
```