本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# CloudWatch Metrics Insights 中的查詢元件和語法
<a name="cloudwatch-metrics-insights-querylanguage"></a>

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)。  
**結構描述**  
可選資料表函數，可以在 **FROM** (從) 子句中使用。使用 **SCHEMA** (結構描述)，將查詢結果範圍縮小為僅完全符合維度清單的指標，或是沒有維度的指標。  
如果您使用 **SCHEMA** (結構描述) 子句，其中必須至少包含一個引數，而且該第一個引數必須是要查詢的指標命名空間。如果您指定僅具有此命名空間引數的 **SCHEMA** (結構描述)，則結果的範圍縮小為僅限於沒有任何維度的指標。  
如果您指定具有其他引數的 **SCHEMA** (結構描述)，則命名空間引數之後的其他引數必須是*標籤*索引鍵。標籤索引鍵必須是維度名稱。如果您指定一或多個這些標籤索引鍵，則結果的範圍僅限於具有完全相同維度集的指標。這些標籤索引鍵的排序並不重要。  
例如：  
+ **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)** 僅符合回報給 CloudWatch 之具有一個維度 `InstanceId` 的 `CPUUtilization` 指標。
+ **SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)** 僅符合從 `AWS/ApplicationELB` 回報給 CloudWatch 之具有兩個維度 `LoadBalancer` 和 `AvailabilityZone` 的 `RequestCount` 指標。

**WHERE**  
選用。使用一或多個標籤索引鍵的特定標籤值，將結果篩選為僅符合指定表達式的指標。例如，**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 子句中使用標籤**  
您可以使用語法 依 AWS 資源標籤篩選結果`tag.keyName`。標籤篩選條件遵循與維度篩選條件相同的運算子規則。例如：  
+ WHERE `tag.env = 'prod'` filters to metrics from resources tagged with *env=prod*
+ WHERE `tag.department != 'test'` excludes metrics from resources tagged with *department=test*
標籤篩選條件可與維度篩選條件結合：  
`WHERE tag.env = 'prod' AND InstanceType = 'm5.large'`  
**支援的運算子**  
**WHERE** (哪裡) 子句支援下列運算子：  
+ **=** 標籤值必須與指定字串相符。
+ **\!=** 標籤值必須與指定字串不相符。
+ **AND** 指定的兩個條件都必須為 true 才能相符。您可以使用多個 **AND** 關鍵字來指定兩個或多個條件。

**GROUP BY**  
選用。將查詢結果分組為多個時間序列，每個時間序列對應於指定的標籤索引鍵或索引鍵的不同值。例如，使用 `GROUP BY InstanceId` 為每個 `InstanceId` 值傳回不同的時間序列。使用 `GROUP BY ServiceName, Operation` 為每個可能的 `ServiceName` 和 `Operation` 值組合建立不同的時間序列。  
使用 **GROUP BY** (分組依據) 子句，預設情況下，結果會根據 **GROUP BY** (分組依據) 子句中指定的標籤序列按字母升冪排序。若要變更結果排序，請新增 **ORDER BY** (排序依據) 子句至您的查詢。  
當您在監控帳戶中執行查詢時，可以使用 `GROUP BY AWS.AccountId` 根據結果來自的帳戶對結果進行分組。  
**在 GROUP BY 子句中使用標籤**  
您可以使用語法 依 AWS 資源標籤值將結果分組`tag.keyName`。例如：  
+ *GROUP BY tag.environment* 為每個環境標籤值建立獨立的時間序列
+ *GROUP BY tag.team, InstanceType* 依標籤和維度值分組
+ *GROUP BY tag.team, AWS.AccountId* 依標籤和連結的來源 AccountID 分組
如果某些相符指標並未包含 **GROUP BY** (分組依據) 子句中指定的特定標籤索引鍵，則會傳回名為 `Other` 的空值群組。例如，如果您指定 `GROUP BY ServiceName, Operation`，且某些傳回的指標不包含 `ServiceName` 作為維度，則這些指標會顯示為像 `ServiceName` 值一樣擁有 `Other`。

**ORDER BY**  
選用。如果查詢傳回一個以上的時間序列，則請指定要用於傳回之時間序列的排序。順序是基於您在 **ORDER BY** (排序依據) 子句中指定的 **FUNCTION** (函數) 所找到的值而定。**FUNCTION** (函數) 用於從每個傳回的時間序列計算單個純量值，並且該值用於確定排序。  
您也可以指定是否使用升冪 **ASC** 或降冪 **DESC** 排序。如果您省略此參數，則預設為升冪 **ASC**。  
例如，新增 `ORDER BY MAX() DESC` 子句會依照時間範圍內觀察到的最大資料點來降冪排序結果：表示會先傳回具有最高最大資料點的時間序列。  
在 **ORDER BY** (排序依據) 子句中使用的有效函數是 `AVG()`、`COUNT()`、`MAX()`、`MIN()` 和 `SUM()`。  
如果您將 **ORDER BY** (排序依據) 子句與 **LIMIT** (限制) 子句搭配使用，則產生的查詢是「前 N」查詢。**ORDER BY** (排序依據) 對可能會傳回大量指標的查詢也很有用，因為每個查詢可傳回不超過 500 個時間序列。如果查詢符合 500 個以上的時間序列，並且您使用 **ORDER BY** (排序依據) 子句，則會排序時間序列，然後排序順序中前 500 個時間序列就是傳回的時間序列。

**LIMIT**  
選用。將查詢傳回的時間序列數量限制為您指定的值。您可以指定的最大值是 500，未指定 **LIMIT** (限制) 的查詢也可以傳回不超過 500 個時間序列。  
將 **LIMIT** (限制) 子句與 **ORDER BY** (排序依據) 子句搭配使用會為您提供「前 N」查詢。

## 什麼需要引號或跳脫字元？
<a name="cloudwatch-metrics-insights-syntaxdetails"></a>

在查詢中，標籤值一律必須以單引號括住。例如，**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)。

## 逐步建置豐富的查詢
<a name="cloudwatch-metrics-insights-syntaxexample"></a>

本節將逐步說明建置使用所有可能子句的完整範例。

可以從以下查詢開始，其彙總了以 `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` 指標彙總至一個時間序列。如果想查看每個可用區域的不同時間序列，可以新增 **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
```

也可以依標籤值對結果分組，而非 (或除了) 維度。例如，依應用程式標籤分組：

```
SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone) WHERE tag.Environment = 'prod' GROUP BY tag.Application ORDER BY MAX() DESC
```

最後，如果主要對「前 N」類型的查詢感興趣，我們可以使用 **LIMIT** (限制) 子句。這最後一個範例將結果限制為僅具有五個最高 `MAX` 值的時間序列。

```
SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
ORDER BY MAX() DESC
LIMIT 5
```

## 跨帳戶查詢範例
<a name="cloudwatch-metrics-insights-crossaccount"></a>

當在 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()
```