Referencia de funciones para la administración de planes de consultas de Aurora PostgreSQL

La extensión apg_plan_mgmt proporciona las siguientes 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. 'disable': deshabilitar cada plan coincidente que no cumpla el factor de aceleración mínimo. 'approve' – habilitar cada plan coincidente que cumpla el factor de aceleración mínimo y establecer su estado en approved. 'reject' – para cada plan coincidente que no cumpla el factor de aceleración mínimo, establecer su estado en rejected. NULL: la función se limita a devolver el número de planes que no tienen beneficios de rendimiento porque no cumplen el factor de aceleración mínimo.

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 '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_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: Un valor de true habilita el plan. Un valor de false deshabilita el plan.

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: 'Approved' 'Unapproved' 'Rejected' 'Preferred' 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_plan_mgmt.dba_plans.

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. 'disable': los planes no válidos se deshabilitan. 'delete': los planes no válidos se eliminan. 'update_plan_hash' – Actualiza el plan_hash ID de los planes que no se pueden reproducir exactamente. También le permite corregir un plan al reescribir el SQL. A continuación, puede registrar el plan en buen estado como un plan Approved para el SQL original. NULL: la función se limita a devolver el número de planes no válidos. No se realiza ninguna otra acción. '': una cadena vacía produce un mensaje que indica el número de planes válidos y no válidos. 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.