# 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"**는 측정기준과 관계없이 `CPUUtilization` 네임스페이스에 있는 `AWS/EC2` 지표와 일치하면 단일 집계된 시계열을 반환합니다.
+ **SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2")**는 정의되지 않은 측정기준이 없는 `AWS/EC2` 네임스페이스에서 `CPUUtilization` 지표와만 일치합니다.
+ **SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId)**는 정확히 하나의 `InstanceId` 측정기준으로 CloudWatch에 보고된 `CPUUtilization` 지표와만 일치합니다.
+ **SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)**는 정확히 `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**. 지정된 두 조건과 모두 일치하려면 true여야 합니다. 여러 **AND** 키워드를 사용하여 2개 이상의 조건을 지정할 수 있습니다.

**GROUP BY**  
선택 사항. 쿼리 결과를 여러 시계열로 그룹화합니다. 각 시계열은 지정된 레이블 키 또는 키에 대한 여러 값에 해당합니다. 예를 들어 `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`이 포함되지 않은 경우 해당 지표는 `ServiceName` 값으로 `Other`를 표시합니다.

**ORDER BY**  
선택 사항. 쿼리가 2개 이상의 시계열을 반환하는 경우 반환된 시계열에 사용할 순서를 지정합니다. 순서는 **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개 이하의 시계열을 반환할 수 있습니다.  
**ORDER BY**가 있는 **LIMIT** 절을 사용하면 "상위 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** 절을 사용할 수 있습니다. 마지막 예에서는 결과를 상위 5개의 `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()
```