Referencia de funciones para la administración de planes de consultas de Aurora PostgreSQL
La extensión apg_plan_mgmt
proporciona las siguientes funciones.
Funciones
apg_plan_mgmt.copy_outline
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.
Parámetros
Parámetro | Descripción |
---|---|
source_sql_hash
|
El identificador del sql_hash asociado al plan_hash para copiar la consulta de destino. |
source_plan_hash |
El identificador del plan_hash que se va a copiar a la consulta de destino. |
target_sql_hash |
El identificador del sql_hash de la consulta que se va a actualizar con el hash y el esquema del plan de origen. |
target_plan_hash |
El identificador del plan_hash de la consulta que se va a actualizar con el hash y el esquema del plan de origen. |
force_update_target_plan_hash |
(Opcional) El ID target_plan_hash de la consulta se actualiza incluso si el plan de origen no es reproducible para eltarget_sql_hash . 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_plan_mgmt.delete_plan
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.
Parámetros
Parámetro | Descripción |
---|---|
sql_hash
|
El ID sql_hash de la instrucción SQL administrada por el plan. |
plan_hash |
El ID plan_hash del plan administrado. |
apg_plan_mgmt.evolve_plan_baselines
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.
Parámetros
Parámetro | Descripción |
---|---|
sql_hash |
El ID sql_hash de la instrucción SQL administrada por el plan. |
plan_hash |
El ID plan_hash del plan administrado. Utilice NULL para referirse a todos los planes que tengan el mismo valor del ID de sql_hash . |
min_speedup_factor |
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.
|
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_plan_mgmt.get_explain_plan
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.
Parámetros
Parámetro | Descripción |
---|---|
sql_hash
|
El ID sql_hash de la instrucción SQL administrada por el plan. |
plan_hash |
El ID plan_hash del plan administrado. |
explainOptionList |
Una lista separada por comas de opciones de explicación. Los valores válidos son |
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_plan_mgmt.plan_last_used
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
.
Parámetros
Parámetro | Descripción |
---|---|
sql_hash
|
El ID sql_hash de la instrucción SQL administrada por el plan. |
plan_hash |
El ID plan_hash del plan administrado. |
apg_plan_mgmt.reload
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.
Parámetros
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_plan_mgmt.set_plan_enabled
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.
Parámetros
Parámetro | Descripción |
---|---|
sql_hash |
El ID sql_hash de la instrucción SQL administrada por el plan. |
plan_hash |
El ID plan_hash del plan administrado. |
enabled |
Valor booleano de verdadero o falso:
|
apg_plan_mgmt.set_plan_status
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.
Parámetros
Parámetro | Descripción |
---|---|
sql_hash |
El ID sql_hash de la instrucción SQL administrada por el plan. |
plan_hash |
El ID plan_hash del plan administrado. |
status |
Cadena con uno de los siguientes valores:
El caso que utilice no importa, pero el valor de estado se establece en mayúscula inicial en la vista |
apg_plan_mgmt.update_plans_last_used
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.
Parámetros
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_plan_mgmt.validate_plans
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.
Parámetros
Parámetro | Descripción |
---|---|
sql_hash |
El ID sql_hash de la instrucción SQL administrada por el plan. |
plan_hash |
El ID plan_hash del plan administrado. Utilice NULL para referirse a todos los planes para el mismo valor del ID de sql_hash . |
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.
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
.