# Aurora PostgreSQL 쿼리 계획 관리를 위한 함수 참조
<a name="AuroraPostgreSQL.Optimize.Functions"></a>

`apg_plan_mgmt` 확장은 다음 함수를 제공합니다.

**Topics**
+ [

## apg\$1plan\$1mgmt.copy\$1outline
](#AuroraPostgreSQL.Optimize.Functions.copy_outline)
+ [

## apg\$1plan\$1mgmt.delete\$1plan
](#AuroraPostgreSQL.Optimize.Functions.delete_plan)
+ [

## apg\$1plan\$1mgmt.evolve\$1plan\$1baselines
](#AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines)
+ [

## apg\$1plan\$1mgmt.get\$1explain\$1plan
](#AuroraPostgreSQL.Optimize.Functions.get_explain_plan)
+ [

## apg\$1plan\$1mgmt.plan\$1last\$1used
](#AuroraPostgreSQL.Optimize.Functions.plan_last_used)
+ [

## apg\$1plan\$1mgmt.reload
](#AuroraPostgreSQL.Optimize.Functions.reload)
+ [

## apg\$1plan\$1mgmt.set\$1plan\$1enabled
](#AuroraPostgreSQL.Optimize.Functions.set_plan_enabled)
+ [

## apg\$1plan\$1mgmt.set\$1plan\$1status
](#AuroraPostgreSQL.Optimize.Functions.set_plan_status)
+ [

## apg\$1plan\$1mgmt.update\$1plans\$1last\$1used
](#AuroraPostgreSQL.Optimize.Functions.update_plans_last_used)
+ [

## apg\$1plan\$1mgmt.validate\$1plans
](#AuroraPostgreSQL.Optimize.Functions.validate_plans)

## apg\$1plan\$1mgmt.copy\$1outline
<a name="AuroraPostgreSQL.Optimize.Functions.copy_outline"></a>

지정된 SQL 계획 해시 및 계획 아웃라인을 대상 SQL 계획 해시 및 아웃라인에 복사하여 대상의 계획 해시 및 아웃라인을 덮어씁니다. 이 함수는 `apg_plan_mgmt` 2.3 이상 릴리스에서 사용할 수 있습니다.

**구문**:

```
apg_plan_mgmt.copy_outline(
    source_sql_hash,
    source_plan_hash,
    target_sql_hash,
    target_plan_hash,
    force_update_target_plan_hash
)
```

**반환 값**  
복사가 성공하면 0을 반환합니다. 입력이 잘못된 경우 예외를 발생시킵니다.

**파라미터**


****  

| 파라미터 | 설명 | 
| --- | --- | 
| source\$1sql\$1hash  | 대상 쿼리에 복사할 plan\$1hash와 관련된 sql\$1hash ID입니다. | 
| source\$1plan\$1hash  | 대상 쿼리에 복사할 plan\$1hash ID입니다. | 
| target\$1sql\$1hash | 소스 플랜 해시 및 아웃라인으로 업데이트할 쿼리의 sql\$1hash ID입니다. | 
| target\$1plan\$1hash | 소스 플랜 해시 및 아웃라인으로 업데이트할 쿼리의 plan\$1hash ID입니다. | 
| force\$1update\$1target\$1plan\$1hash | (선택 사항) target\$1sql\$1hash에 대한 소스 계획을 재현할 수 없는 경우에도 쿼리의 target\$1plan\$1hash ID가 업데이트됩니다. true로 설정하면 함수를 사용하여 관계 이름과 열이 일치하는 스키마 간에 계획을 복사할 수 있습니다. | 

**사용 노트**:

이 함수를 사용하면 힌트를 사용하는 계획 해시 및 계획 개요를 다른 유사한 문에 복사할 수 있으므로, 대상 문에서 발생할 때마다 인라인 힌트 문을 사용하지 않아도 됩니다. 업데이트된 대상 쿼리 때문에 잘못된 계획이 생성되는 경우, 이 함수는 오류를 발생시키고 시도한 업데이트를 롤백합니다.

## apg\$1plan\$1mgmt.delete\$1plan
<a name="AuroraPostgreSQL.Optimize.Functions.delete_plan"></a>

관리형 계획을 삭제합니다.

**구문**:

```
apg_plan_mgmt.delete_plan(
    sql_hash,
    plan_hash
)
```

**반환 값**  
삭제가 성공한 경우 0을 반환하고, 실패한 경우 -1을 반환합니다.

**파라미터**


****  

| 파라미터 | 설명 | 
| --- | --- | 
| sql\$1hash  | 계획의 관리형 SQL 문의 sql\$1hash ID. | 
| plan\$1hash | 관리형 계획의 plan\$1hash ID. | 

 

## apg\$1plan\$1mgmt.evolve\$1plan\$1baselines
<a name="AuroraPostgreSQL.Optimize.Functions.evolve_plan_baselines"></a>

이미 승인된 계획이 더 빠른지 여부 또는 쿼리 최적화 프로그램에서 최소 비용 계획으로 식별된 계획이 더 빠른지 여부를 확인합니다.

**구문**:

```
apg_plan_mgmt.evolve_plan_baselines(
    sql_hash, 
    plan_hash,
    min_speedup_factor,
    action
)
```

**반환 값**

승인된 최상의 계획보다 빠르지 않은 계획 수.

**파라미터**


****  

| 파라미터 | 설명 | 
| --- | --- | 
| sql\$1hash | 계획의 관리형 SQL 문의 sql\$1hash ID. | 
| plan\$1hash | 관리형 계획의 plan\$1hash ID. sql\$1hash ID 값이 동일한 모든 계획의 평균을 구하려면 NULL을 사용합니다. | 
| min\$1speedup\$1factor |  *최소 속도 향상 인수*는 계획이 승인되려면 이미 승인된 계획 중 최상의 계획보다 몇 배 더 빨라야 하는지를 지정합니다. 또는 거부되거나 비활성화되려면 몇 배 더 느려야 하는지를 지정할 수도 있습니다. 이 값은 양수 부동 값입니다.  | 
| action |  함수가 수행해야 할 작업입니다. 유효 값에는 다음이 포함됩니다. 대/소문자를 구분하지 않습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html)  | 

**사용 노트**

계획 \$1 실행 시간이 설정한 인수만큼 최상의 승인된 계획보다 더 빠른지 여부에 따라 지정된 계획을 승인됨, 거부됨 또는 비활성화됨으로 설정합니다. 이 작업 파라미터를 `'approve'` 또는 `'reject'`로 설정하여 성능 기준을 충족하는 계획을 자동으로 승인하거나 거부할 수 있습니다. 또는 "(빈 문자열)로 설정하여 성능 실험을 수행한 후 보고서만 생성하고 아무런 작업도 취하지 않을 수 있습니다.

최근에 실행된 계획에 대해 `apg_plan_mgmt.evolve_plan_baselines` 함수를 무의미하게 다시 실행하는 일을 방지할 수 있습니다. 이를 위해서는 최근에 생성한 미승인 계획까지만 계획을 제한하십시오. 또는 최근 `apg_plan_mgmt.evolve_plan_baselines` 타임스탬프가 있는 승인된 계획에서만 `last_verified` 함수를 실행하지 않도록 할 수 있습니다.

성능 실험을 수행하여 기준 내 다른 계획과 각 계획의 계획 \$1 실행 시간을 비교합니다. 경우에 따라서는 설명문에 대해 계획 하나만 있고 해당 계획이 승인된 계획일 수 있습니다. 이러한 경우에는 계획의 계획 \$1 실행 시간과 아무런 계획도 사용하지 않을 때의 계획 \$1 실행 시간을 비교합니다.

각 계획의 증분형 이점(또는 단점)이 `apg_plan_mgmt.dba_plans` 열의 `total_time_benefit_ms` 보기에 기록됩니다. 이 값이 양수이면 기준에 이 계획을 포함할 경우 주목할 만한 성능 개선이 있는 것입니다.

각 후보 계획의 계획 \$1 실행 시간을 수집할 뿐만 아니라, `last_verified` 보기의 `apg_plan_mgmt.dba_plans` 열이 `current_timestamp`로 업데이트됩니다. `last_verified` 타임스탬프를 사용하면 최근에 성능이 확인된 계획에 대해 이 함수가 다시 실행되지 않도록 할 수 있습니다.

## apg\$1plan\$1mgmt.get\$1explain\$1plan
<a name="AuroraPostgreSQL.Optimize.Functions.get_explain_plan"></a>

지정한 SQL 문에 대한 `EXPLAIN` 문의 텍스트를 생성합니다.

**구문**:

```
apg_plan_mgmt.get_explain_plan(
    sql_hash,
    plan_hash,
    [explainOptionList]
)
```

**반환 값**  
지정한 SQL 문에 대한 런타임 통계를 반환합니다. 간단한 `explainOptionList` 계획을 반환하려면 `EXPLAIN` 없이 사용합니다.

**파라미터**


****  

| 파라미터 | 설명 | 
| --- | --- | 
| sql\$1hash  | 계획의 관리형 SQL 문의 sql\$1hash ID. | 
| plan\$1hash | 관리형 계획의 plan\$1hash ID. | 
| explainOptionList | 설명 옵션을 쉼표로 구분한 목록입니다. 유효한 값으로는 `'analyze'`, `'verbose'`, `'buffers'`, `'hashes'` 및 `'format json'`이 있습니다. `explainOptionList`가 NULL이거나 빈 문자열('')인 경우 이 함수는 통계 데이터 없이 `EXPLAIN` 문을 생성합니다.  | 

 

**사용 노트**

`explainOptionList`의 경우 `EXPLAIN` 문에 사용하는 것과 동일한 옵션 중 하나를 사용할 수 있습니다. Aurora PostgreSQL 옵티마이저는 사용자가 `EXPLAIN` 문에 제공항하는 옵션 목록을 연결합니다.

## apg\$1plan\$1mgmt.plan\$1last\$1used
<a name="AuroraPostgreSQL.Optimize.Functions.plan_last_used"></a>

공유 메모리에서 지정된 계획의 `last_used` 날짜를 반환합니다.

**참고**  
공유 메모리의 값은 DB 클러스터의 기본 DB 인스턴스에서 항상 최신 상태입니다. 값은 `apg_plan_mgmt.dba_plans` 뷰의 `last_used` 열에 주기적으로 플러시됩니다.

**구문**:

```
apg_plan_mgmt.plan_last_used(
    sql_hash,
    plan_hash
)
```

**반환 값**  
`last_used` 날짜를 반환합니다.

**파라미터**


****  

| 파라미터 | 설명 | 
| --- | --- | 
| sql\$1hash  | 계획의 관리형 SQL 문의 sql\$1hash ID. | 
| plan\$1hash | 관리형 계획의 plan\$1hash ID. | 

 

## apg\$1plan\$1mgmt.reload
<a name="AuroraPostgreSQL.Optimize.Functions.reload"></a>

계획을 `apg_plan_mgmt.dba_plans` 보기에서 공유 메모리로 다시 로드합니다.

**구문**:

```
apg_plan_mgmt.reload()
```

**반환 값**

없음.

**파라미터**

없음.

**사용 노트**

다음 상황의 경우 `reload`를 호출합니다.
+ 새 계획이 복제본으로 전파될 때까지 기다리기 보다는 이 함수를 사용하여 읽기 전용 복제본의 공유 메모리를 즉시 새로 고칩니다.
+ 관리형 계획을 가져온 후에 사용합니다.



## apg\$1plan\$1mgmt.set\$1plan\$1enabled
<a name="AuroraPostgreSQL.Optimize.Functions.set_plan_enabled"></a>

관리형 계획을 활성화하거나 비활성화합니다.

**구문**:

```
apg_plan_mgmt.set_plan_enabled(
    sql_hash, 
    plan_hash, 
    [true | false]
)
```

**반환 값**

설정이 성공한 경우 0을 반환하고, 실패한 경우 -1을 반환합니다.

**파라미터**


****  

| 파라미터 | 설명 | 
| --- | --- | 
| sql\$1hash | 계획의 관리형 SQL 문의 sql\$1hash ID. | 
| plan\$1hash | 관리형 계획의 plan\$1hash ID. | 
| enabled |  부울 값(true 또는 false): [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html)  | 

 

## apg\$1plan\$1mgmt.set\$1plan\$1status
<a name="AuroraPostgreSQL.Optimize.Functions.set_plan_status"></a>

관리된 계획의 상태를 `Approved`, `Unapproved`, `Rejected` 또는 `Preferred`로 설정합니다.

**구문**:

```
apg_plan_mgmt.set_plan_status(
    sql_hash, 
    plan_hash, 
    status
)
```

**반환 값**

설정이 성공한 경우 0을 반환하고, 실패한 경우 -1을 반환합니다.

**파라미터**


****  

| 파라미터 | 설명 | 
| --- | --- | 
| sql\$1hash | 계획의 관리형 SQL 문의 sql\$1hash ID. | 
| plan\$1hash | 관리형 계획의 plan\$1hash ID. | 
| status |  다음 값 중 하나를 가진 문자열: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) 대문자를 사용하든 소문자를 사용하든 `apg_plan_mgmt.dba_plans` 보기에서 상태 값은 초기 대문자로 설정됩니다. 이러한 값에 대한 자세한 내용은 `status`의 [Aurora PostgreSQL 호환 에디션의 apg\$1plan\$1mgmt.dba\$1plans 뷰에 대한 참조](AuroraPostgreSQL.Optimize.dba_plans_view_Reference.md)를 참조하세요.  | 

 

## apg\$1plan\$1mgmt.update\$1plans\$1last\$1used
<a name="AuroraPostgreSQL.Optimize.Functions.update_plans_last_used"></a>

공유 메모리에 저장됭 `last_used` 날짜로 계획 테이블을 즉시 업데이트합니다.

**구문**:

```
apg_plan_mgmt.update_plans_last_used()
```

**반환 값**

없음.

**파라미터**

없음.

**사용 노트**

`dba_plans.last_used` 열에 대항하는 쿼리가 가장 최신 정보를 사용하도록 `update_plans_last_used`를 호출합니다. 만약 `last_used` 날짜가 즉시 업데이트되지 않는다면, 백그라운드 프로세스가 계획 테이블을 `last_used` 날짜로 1시간에 한 번씩(기본값) 업데이트합니다.

예를 들어, 특정 `sql_hash`가 있는 명령문이 느리게 실행되기 시작하면, 성능 회귀 분석이 시작된 이후 해당 명령문에 대해 어떤 계획이 실행되었는지 확인할 수 있습니다. 이렇게 하려면 먼저 공유 메모리의 데이터를 디스크로 플러시하여 `last_used` 날짜가 현재 날짜이고, 그런 다음 성능 회귀가 있는 명령문의 `sql_hash`의 모든 계획을 쿼리합니다. 쿼리에서 `last_used` 날짜가 성능 회귀 분석이 시작된 날짜보다 크거나 같은지 확인하세요. 쿼리는 성과 회귀를 담당할 수 있는 계획 또는 계획 집합을 식별합니다. `apg_plan_mgmt.get_explain_plan`과 `explainOptionList`를 사용하여 `verbose, hashes`로 설정할 수 있습니다. 또한 `apg_plan_mgmt.evolve_plan_baselines`를 통해 계획과 더 나은 성능을 발휘할 수 있는 대체 계획을 분석할 수 있습니다.

`update_plans_last_used` 함수는 DB 클러스터의 기본 DB 인스턴스에만 영향을 줍니다.

## apg\$1plan\$1mgmt.validate\$1plans
<a name="AuroraPostgreSQL.Optimize.Functions.validate_plans"></a>

최적화 프로그램에서 계획을 여전히 다시 생성할 수 있는지 검증합니다. 최적화 프로그램은 계획의 활성 또는 비활성 여부와 상관없이 `Approved`, `Unapproved` 및 `Preferred` 계획을 검증합니다. `Rejected` 계획은 검증되지 않습니다. 원할 경우 `apg_plan_mgmt.validate_plans` 함수를 사용하여 유효하지 않은 계획을 삭제하거나 비활성화할 수 있습니다.

**구문**:

```
apg_plan_mgmt.validate_plans(
    sql_hash, 
    plan_hash, 
    action)
            
apg_plan_mgmt.validate_plans(
    action)
```

**반환 값**

잘못된 계획 수.

**파라미터**


****  

| 파라미터 | 설명 | 
| --- | --- | 
| sql\$1hash | 계획의 관리형 SQL 문의 sql\$1hash ID. | 
| plan\$1hash | 관리형 계획의 plan\$1hash ID. 동일한 sql\$1hash ID 값에 대한 모든 계획의 평균을 구하려면 NULL을 사용합니다. | 
| action |  함수에서 잘못된 계획에 대해 수행할 작업. 유효한 문자열 값에는 다음이 포함됩니다. 대/소문자를 구분하지 않습니다. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) 그 밖의 값은 빈 문자열로 간주됩니다.  | 

**사용 노트**

전체 `validate_plans(action)` 보기의 모든 관리형 설명문에 대해 모든 관리형 계획을 검증하려면 `apg_plan_mgmt.dba_plans` 형태를 사용합니다.

`validate_plans(sql_hash, plan_hash, action)`가 지정된 관리형 설명문의 경우 `plan_hash`가 지정된 관리형 계획을 검증하려면 `sql_hash` 형태를 사용합니다.

`validate_plans(sql_hash, NULL, action)`가 지정된 관리형 설명문에 대해 모든 관리형 계획을 검증하려면 `sql_hash` 형태를 사용합니다.