# Referencia de funciones para la administración de planes de consultas de Aurora PostgreSQL
<a name="AuroraPostgreSQL.Optimize.Functions"></a>

La extensión `apg_plan_mgmt` proporciona las siguientes funciones.

**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>

Copia un hash del plan SQL y un esquema del plan determinados en un hash del plan SQL y un esquema del plan de destino, por lo que sobrescribe el hash y el esquema del plan de destino. Esta función está disponible en las versiones 2.3 y posteriores de `apg_plan_mgmt`. 

**Sintaxis**

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

**Valor devuelto**  
Devuelve 0 si la copia se ha realizado correctamente. Genera excepciones para entradas no válidas.

**Parameters**


****  

| Parámetro | Descripción | 
| --- | --- | 
| source\$1sql\$1hash  | El identificador del sql\$1hash asociado al plan\$1hash para copiar la consulta de destino. | 
| source\$1plan\$1hash  | El identificador del plan\$1hash que se va a copiar a la consulta de destino. | 
| target\$1sql\$1hash | El identificador del sql\$1hash de la consulta que se va a actualizar con el hash y el esquema del plan de origen. | 
| target\$1plan\$1hash | El identificador del plan\$1hash de la consulta que se va a actualizar con el hash y el esquema del plan de origen. | 
| force\$1update\$1target\$1plan\$1hash | (Opcional) El ID target\$1plan\$1hash de la consulta se actualiza incluso si el plan de origen no es reproducible para eltarget\$1sql\$1hash. Si se establece en true, la función se puede utilizar para copiar planes de varios esquemas en los que los nombres de las relaciones y las columnas sean coherentes. | 

**Notas de uso**

Esta función le permite copiar un hash de plan y un esquema de plan que utiliza sugerencias a otras instrucciones similares, y le evita así tener que utilizar instrucciones de sugerencias en línea en cada ocurrencia en las instrucciones de destino. Si la consulta de destino actualizada da como resultado un plan no válido, esta función genera un error y revierte el intento de actualización. 

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

Eliminar un plan administrado. 

**Sintaxis**

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

**Valor devuelto**  
Devuelve 0 si la eliminación se ha realizado correctamente o -1 si en la eliminación se ha producido un error.

**Parameters**


****  

| Parámetro | Descripción | 
| --- | --- | 
| sql\$1hash  | El ID sql\$1hash de la instrucción SQL administrada por el plan. | 
| plan\$1hash | El ID plan\$1hash del plan administrado. | 

 

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

Comprueba si un plan ya aprobado es más rápido o si un plan identificado por el optimizador de consultas como plan de costo mínimo es más rápido.

**Sintaxis**

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

**Valor devuelto**

El número de planes que no han sido más rápidos que el mejor plan aprobado. 

**Parameters**


****  

| Parámetro | Descripción | 
| --- | --- | 
| sql\$1hash | El ID sql\$1hash de la instrucción SQL administrada por el plan. | 
| plan\$1hash | El ID plan\$1hash del plan administrado. Utilice NULL para referirse a todos los planes que tengan el mismo valor del ID de sql\$1hash. | 
| min\$1speedup\$1factor |  El *factor de aceleración mínimo* es el número de veces más rápido que debe ser un plan en relación con los planes ya aprobados para aprobarlo. Este factor puede ser también el número de veces más lento que debe ser un plan para rechazarlo o deshabilitarlo. Este valor es un número flotante positivo.  | 
| action |  La acción que va a realizar la función. Entre los valores válidos se incluyen los siguientes. No distingue entre mayúsculas y minúsculas.  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html)  | 

** Notas de uso**

Establecer planes específicos como aprobados, rechazados o deshabilitados en función de si el tiempo de planificación más el de ejecución es más rápido que el mejor plan aprobado por un factor que puede configurar. El parámetro de acción puede establecerse en `'approve'` o `'reject'` para aprobar o rechazar automáticamente un plan que cumpla los criterios de rendimiento. Como alternativa, podría establecerse como " (cadena vacía) para realizar el experimento de rendimiento y producir un informe, sin realizar ninguna acción.

Puede evitar una nueva ejecución sin sentido de la función `apg_plan_mgmt.evolve_plan_baselines` para un plan en el que se ha ejecutado recientemente. Para ello, restrinja los planes a los planes sin aprobar creados recientemente. Como alternativa, puede evitar la ejecución de la función `apg_plan_mgmt.evolve_plan_baselines` en cualquier plan aprobado que tenga una marca temporal `last_verified` reciente.

Realizar un experimento de rendimiento para comparar el tiempo de planificación más el de ejecución para cada plan en relación con los demás planes de la base de referencia. En algunos casos, solo hay un plan para una instrucción, y el plan está aprobado. En tal caso, compare el tiempo de planificación más ejecución del plan con el tiempo de planificación más ejecución de no usar ningún plan.

El beneficio (o desventaja) incremental de cada plan queda registrado en la vista `apg_plan_mgmt.dba_plans` de la columna `total_time_benefit_ms`. Si este valor es positivo, existe un beneficio de rendimiento medible al incluir este plan en la base de referencia.

Además de recopilar el tiempo de planificación y ejecución de cada plan candidato, la columna `last_verified` de la vista `apg_plan_mgmt.dba_plans` se actualiza con el `current_timestamp`. La marca temporal `last_verified` se podría utilizar para evitar la ejecución de esta función de nuevo en un plan cuyo rendimiento se haya verificado recientemente.

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

Genera el texto de una instrucción `EXPLAIN` para la instrucción SQL especificada. 

**Sintaxis**

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

**Valor devuelto**  
Devuelve estadísticas de tiempo de ejecución para las instrucciones SQL especificadas. Utilizar sin `explainOptionList` para devolver un plan `EXPLAIN` simple.

**Parameters**


****  

| Parámetro | Descripción | 
| --- | --- | 
| sql\$1hash  | El ID sql\$1hash de la instrucción SQL administrada por el plan. | 
| plan\$1hash | El ID plan\$1hash del plan administrado. | 
| explainOptionList | Una lista separada por comas de opciones de explicación. Los valores válidos son `'analyze'`, `'verbose'`, `'buffers'`, `'hashes'` y `'format json'`. Si la lista de `explainOptionList` es NULL o una cadena vacía (''), esta función genera una instrucción `EXPLAIN`, sin ninguna estadística.  | 

 

**Notas de uso**

Para `explainOptionList`, puede usar cualquiera de las mismas opciones que usaría con una instrucción `EXPLAIN`. El optimizador de Aurora PostgreSQL concatena la lista de opciones que proporciona a la instrucción `EXPLAIN`.

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

Devuelve la fecha `last_used` del plan especificado de la memoria compartida. 

**nota**  
El valor de la memoria compartida siempre es actual en la instancia de base de datos principal del clúster de base de datos. El valor solo se vacía periódicamente en la columna `last_used` de la vista `apg_plan_mgmt.dba_plans`.

**Sintaxis**

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

**Valor devuelto**  
Devuelve la fecha `last_used`.

**Parameters**


****  

| Parámetro | Descripción | 
| --- | --- | 
| sql\$1hash  | El ID sql\$1hash de la instrucción SQL administrada por el plan. | 
| plan\$1hash | El ID plan\$1hash del plan administrado. | 

 

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

Vuelve a cargar los planes en la memoria compartida desde la vista `apg_plan_mgmt.dba_plans`. 

**Sintaxis**

```
apg_plan_mgmt.reload()
```

**Valor devuelto**

Ninguno.

**Parameters**

Ninguna.

** Notas de uso**

Llame a `reload` para las siguientes situaciones:
+ Utilícelo para actualizar la memoria compartida de una réplica de solo lectura inmediatamente, en lugar de esperar a que los nuevos planes propaguen la réplica.
+ Se utiliza tras importar los planes administrados.



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

Habilitar o deshabilitar un plan administrado.

**Sintaxis**

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

**Valor devuelto**

Devuelve 0 si el ajuste se ha realizado correctamente o -1 si en el ajuste se ha producido un error.

**Parameters**


****  

| Parámetro | Descripción | 
| --- | --- | 
| sql\$1hash | El ID sql\$1hash de la instrucción SQL administrada por el plan. | 
| plan\$1hash | El ID plan\$1hash del plan administrado. | 
| enabled |  Valor booleano de verdadero o falso: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html)  | 

 

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

Establezca el estado de un plan administrado en `Approved`, `Unapproved`, `Rejected` o `Preferred`.

**Sintaxis**

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

**Valor devuelto**

Devuelve 0 si el ajuste se ha realizado correctamente o -1 si en el ajuste se ha producido un error.

**Parameters**


****  

| Parámetro | Descripción | 
| --- | --- | 
| sql\$1hash | El ID sql\$1hash de la instrucción SQL administrada por el plan. | 
| plan\$1hash | El ID plan\$1hash del plan administrado. | 
| status |  Cadena con uno de los siguientes valores: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) El caso que utilice no importa, pero el valor de estado se establece en mayúscula inicial en la vista `apg_plan_mgmt.dba_plans`. Para obtener más información acerca de estos valores de la tarea, consulte `status` en [Referencia de la vista apg\$1plan\$1mgmt.dba\$1plans para la edición compatible con Aurora PostgreSQL](AuroraPostgreSQL.Optimize.dba_plans_view_Reference.md).   | 

 

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

Actualiza inmediatamente la tabla de planes con la fecha de `last_used` almacenada en la memoria compartida.

**Sintaxis**

```
apg_plan_mgmt.update_plans_last_used()
```

**Valor devuelto**

Ninguno.

**Parameters**

Ninguna.

** Notas de uso**

Llame a `update_plans_last_used` para asegurarse de que las consultas de la columna `dba_plans.last_used` utilizan la información más actualizada. Si el archivo de la fecha de `last_used` no se actualiza inmediatamente, un proceso en segundo plano actualiza la tabla de planes con la fecha de `last_used` una vez cada hora (de forma predeterminada).

Por ejemplo, si una instrucción con un `sql_hash` determinado comienza a ejecutarse lentamente, puede determinar qué planes para esa instrucción se ejecutaron desde que comenzó la regresión de rendimiento. Para ello, primero vacíe los datos de la memoria compartida al disco para que las fechas de `last_used` estén actualizadas y, a continuación, consulte todos los planes de `sql_hash` de la instrucción con la regresión del rendimiento. En la consulta, asegúrese de que la fecha de `last_used` es superior o igual que la fecha en que comenzó la regresión del rendimiento. La consulta identifica el plan o conjunto de planes que podrían ser responsables de la regresión del rendimiento. Puede usar `apg_plan_mgmt.get_explain_plan` con `explainOptionList` establecidos en `verbose, hashes`. También puede utilizar `apg_plan_mgmt.evolve_plan_baselines` para analizar el plan y cualquier plan alternativo que pueda funcionar mejor.

La función `update_plans_last_used` tiene efecto únicamente en la instancia de base de datos principal del clúster de base de datos.

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

Validar que el optimizador aún puede recrear planes. El optimizador valida los planes `Approved`, `Unapproved` y `Preferred`, aunque el plan esté habilitado o deshabilitado. Los planes `Rejected` no se validan. Opcionalmente, puede usar la función `apg_plan_mgmt.validate_plans` para eliminar o deshabilitar planes no válidos.

**Sintaxis**

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

**Valor devuelto**

Número de planes no válidos.

**Parameters**


****  

| Parámetro | Descripción | 
| --- | --- | 
| sql\$1hash | El ID sql\$1hash de la instrucción SQL administrada por el plan. | 
| plan\$1hash | El ID plan\$1hash del plan administrado. Utilice NULL para referirse a todos los planes para el mismo valor del ID de sql\$1hash. | 
| action |  La acción que va a realizar la función para los planes no válidos. Entre los valores de cadena válidos se incluyen los siguientes. No distingue entre mayúsculas y minúsculas. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) Cualquier otro valor se trata como una cadena vacía.  | 

**Notas de uso**

Utilice el formulario `validate_plans(action)` para validar todos los planes administrados para las instrucciones administradas en toda la vista `apg_plan_mgmt.dba_plans`.

Utilice el formulario `validate_plans(sql_hash, plan_hash, action)` para validar un plan administrado especificado con `plan_hash`, para una instrucción administrada especificada con `sql_hash`. 

Utilice el formulario `validate_plans(sql_hash, NULL, action)` para validar todos los planes administrados para una instrucción administrada especificada con `sql_hash`.