Referência de funções do gerenciamento de planos de consultas do Aurora PostgreSQL

A extensão apg_plan_mgmt fornece as funções a seguir.

apg_plan_mgmt.copy_outline

Copie um determinado hash do plano SQL e o esboço do plano para um hash e um esboço do plano SQL de destino, substituindo assim o hash e o esboço do plano de destino. Essa função está disponível no apg_plan_mgmt 2.3 e superiores.

Sintaxe

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

Valor de retorno

Retorna 0 quando a cópia é bem-sucedida. Gera exceções para entradas inválidas.

Parâmetros

Parâmetro	Descrição
source_sql_hash	O ID sql_hash associado ao plan_hash a ser copiado na consulta de destino.
source_plan_hash	O ID plan_hash a ser copiado na consulta de destino.
target_sql_hash	O ID sql_hash da consulta a ser atualizada com o hash e o esboço do plano de origem.
target_plan_hash	O ID plan_hash da consulta a ser atualizada com o hash e o esboço do plano de origem.
force_update_target_plan_hash	(Opcional) O ID target_plan_hash da consulta é atualizado mesmo que o plano de origem não seja reproduzível para o target_sql_hash. Quando definida como verdadeira, a função pode ser usada para copiar planos em esquemas em que os nomes e as colunas das relações são consistentes.

Observações de uso

Essa função permite que você copie um hash do plano e um esboço do plano que usam dicas para outras declarações semelhantes e, assim, evita que você precise usar instruções de dica em linha em cada ocorrência nas declarações de destino. Se a consulta de destino atualizada ocasionar um plano inválido, essa função gerará um erro e reverterá a tentativa de atualização.

apg_plan_mgmt.delete_plan

Exclua um plano gerenciado.

Sintaxe

apg_plan_mgmt.delete_plan(
    sql_hash,
    plan_hash
) 

Valor de retorno

Retorna 0 caso a exclusão tenha sido bem-sucedida ou -1 em caso de falha na exclusão.

Parâmetros

Parâmetro	Descrição
sql_hash	O ID sql_hash da instrução SQL gerenciada do plano.
plan_hash	O ID plan_hash do plano gerenciado.

apg_plan_mgmt.evolve_plan_baselines

Verifica se um plano já aprovado é mais rápido ou se um plano identificado pelo otimizador de consultas como um plano de custo mínimo é mais rápido.

Sintaxe

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

Valor de retorno

O número de planos que não eram mais rápidos do que o melhor plano aprovado.

Parâmetros

Parâmetro	Descrição
sql_hash	O ID sql_hash da instrução SQL gerenciada do plano.
plan_hash	O ID plan_hash do plano gerenciado. Use NULL como média de todos os planos que tenham o mesmo valor de ID sql_hash.
min_speedup_factor	O fator de agilização mínimo pode ser o número de vezes mais rápido que um plano deve ser em relação ao melhor dos planos já aprovados para aprová-lo. Como alternativa, esse fator pode ser o número de vezes mais lento que um plano deve ser para rejeitá-lo ou desabilitá-lo. Trata-se de um valor flutuante positivo.
action	A ação que a função deve realizar. Entre os valores válidos estão os seguintes. O uso de maiúsculas ou minúsculas não importa. 'disable' – desabilite cada plano correspondente que não atenda ao fator de agilização mínimo. 'approve' – habilite cada plano correspondente que atenda ao fator de agilização mínimo e defina seu status como approved. 'reject' – para cada plano correspondente que não atenda ao fator de agilização mínimo, defina o status como rejected. NULL – a função simplesmente retorna o número de planos sem benefícios quanto à performance porque eles não atendem ao fator de agilização mínimo.

Observações de uso

Defina planos especificados como aprovados, rejeitados ou desabilitados com base na velocidade do planejamento mais o tempo de execução ser maior ou não que o melhor plano aprovado por um fator definido por você. O parâmetro de ação pode ser definido como 'approve' ou 'reject' para aprovar ou rejeitar automaticamente um plano que atenda aos critérios de performance. Como alternativa, ele pode ser definido como '' (string vazia) para realizar o experimento de performance e produzir um relatório, mas não realizar ação.

Você pode evitar a reexecução infundada da função apg_plan_mgmt.evolve_plan_baselines de um plano no qual ela foi executada recentemente. Para isso, restrinja os planos a apenas os planos não aprovados criados recentemente. Também é possível evitar executar a função apg_plan_mgmt.evolve_plan_baselines em qualquer plano aprovado que tenha um timestamp last_verified recente.

Realize um experimento de performance para comparar o tempo de planejamento mais execução de cada plano relativo aos outros planos na linha de base. Em alguns casos, talvez haja somente um plano para uma instrução e o plano seja aprovado. Nesse caso, compare o tempo de planejamento mais execução do plano com o tempo de planejamento mais execução de nenhum plano usado.

O benefício incremental (ou desvantagem) de cada plano é registrado na visualização apg_plan_mgmt.dba_plans na coluna total_time_benefit_ms. Quando esse valor é positivo, há uma vantagem de performance mensurável em incluir esse plano na linha de base.

Além de coletar o tempo de planejamento e execução de cada plano candidato, a coluna last_verified da visualização apg_plan_mgmt.dba_plans é atualizada com o current_timestamp. O time stamp last_verified pode ser usado para evitar a reexecução dessa função em um plano que recentemente teve a verificação da performance.

apg_plan_mgmt.get_explain_plan

Gera o texto de uma instrução EXPLAIN para a instrução SQL especificada.

Sintaxe

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

Valor de retorno

Retorna estatísticas de tempo de execução para as instruções SQL especificadas. Use sem explainOptionList para retornar um plano EXPLAIN simples.

Parâmetros

Parâmetro	Descrição
sql_hash	O ID sql_hash da instrução SQL gerenciada do plano.
plan_hash	O ID plan_hash do plano gerenciado.
explainOptionList	Uma lista separada por vírgulas com opções de explicação. Os valores válidos incluem 'analyze', 'verbose', 'buffers', 'hashes' e 'format json'. Se a lista de explainOptionList for NULL (NULA) ou uma string vazia (''), essa função gerará uma instrução EXPLAIN sem nenhuma estatística.

Observações de uso

Para a explainOptionList, você pode usar qualquer uma das mesmas opções que você usaria com uma instrução EXPLAIN. O otimizador do Aurora PostgreSQL concatena a lista de opções que você fornece à instrução EXPLAIN.

apg_plan_mgmt.plan_last_used

Retorna a data last_used do plano especificado da memória compartilhada.

nota

O valor na memória compartilhada é sempre atual na instância de banco de dados primária do cluster de banco de dados. Esse valor é apenas periodicamente liberado na coluna last_used da visualização apg_plan_mgmt.dba_plans.

Sintaxe

apg_plan_mgmt.plan_last_used(
    sql_hash,
    plan_hash
) 

Valor de retorno

Retorna a data last_used.

Parâmetros

Parâmetro	Descrição
sql_hash	O ID sql_hash da instrução SQL gerenciada do plano.
plan_hash	O ID plan_hash do plano gerenciado.

apg_plan_mgmt.reload

Recarregue planos na memória compartilhada da visualização apg_plan_mgmt.dba_plans.

Sintaxe

apg_plan_mgmt.reload()

Valor de retorno

Nenhum.

Parâmetros

Nenhum.

Observações de uso

Chame reload para as seguintes situações:

• Use-o para atualizar a memória compartilhada de uma réplica somente leitura imediatamente, em vez de aguardar a propagação de novos planos para a réplica.

• Use-o após a importação de planos gerenciados.

apg_plan_mgmt.set_plan_enabled

Habilite ou desabilite um plano gerenciado.

Sintaxe

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

Valor de retorno

Retorna 0 caso a definição tenha sido bem-sucedida ou -1 em caso de falha na definição.

Parâmetros

Parâmetro	Descrição
sql_hash	O ID sql_hash da instrução SQL gerenciada do plano.
plan_hash	O ID plan_hash do plano gerenciado.
enabled	Valores boolianos de verdadeiro ou falso: Um valor de true habilita o plano. Um valor de false desabilita o plano.

apg_plan_mgmt.set_plan_status

Defina o status de um plano gerenciado como Approved, Unapproved, Rejected, ou Preferred.

Sintaxe

apg_plan_mgmt.set_plan_status(
    sql_hash, 
    plan_hash, 
    status
)

Valor de retorno

Retorna 0 caso a definição tenha sido bem-sucedida ou -1 em caso de falha na definição.

Parâmetros

Parâmetro	Descrição
sql_hash	O ID sql_hash da instrução SQL gerenciada do plano.
plan_hash	O ID plan_hash do plano gerenciado.
status	Uma string com um dos seguintes valores: 'Approved' 'Unapproved' 'Rejected' 'Preferred' A formatação de maiúsculas/minúsculas usada não importa. No entanto, o valor do status é definido com maiúsculas iniciais na visualização apg_plan_mgmt.dba_plans. Para obter mais informações sobre esses valores, consulte status em Referência da visualização apg_plan_mgmt.dba_plans.

apg_plan_mgmt.update_plans_last_used

Atualiza imediatamente a tabela de planos com a data de last_used armazenada na memória compartilhada.

Sintaxe

apg_plan_mgmt.update_plans_last_used()

Valor de retorno

Nenhum.

Parâmetros

Nenhum.

Observações de uso

Chame update_plans_last_used para garantir que as consultas na coluna dba_plans.last_used usem as informações mais atuais. Se a data last_used não for atualizada imediatamente, um processo em segundo plano atualizará a tabela de planos com a data de last_used uma vez a cada hora (por padrão).

Por exemplo, se uma instrução com um determinado sql_hash começar a ser executada lentamente, será possível determinar quais planos para essa instrução foram executados desde que a regressão de performance começou. Para fazer isso, primeiro descarregue os dados da memória compartilhada no disco para que as datas de last_used sejam atuais e, em seguida, consulte todos os planos de sql_hash da instrução com a regressão de performance. Na consulta, certifique-se de que a data de last_used seja igual ou posterior à data em que a regressão de performance começou. A consulta identifica o plano ou o conjunto de planos que pode ser o responsável pela regressão de performance. Você pode utilizar apg_plan_mgmt.get_explain_plan com explainOptionList definido como verbose, hashes. Também é possível utilizar apg_plan_mgmt.evolve_plan_baselines para analisar o plano e quaisquer planos alternativos que possam ter performance melhor.

A função update_plans_last_used tem efeito somente na instância de banco de dados primária do cluster de banco de dados.

apg_plan_mgmt.validate_plans

Valide se o otimizador ainda pode recriar planos. O otimizador valida os planos Approved, Unapproved e Preferred, independentemente de o plano estar ativado ou desativado. Planos Rejected não são validados. Também é possível usar a função apg_plan_mgmt.validate_plans para excluir ou desabilitar planos inválidos.

Sintaxe

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

Valor de retorno

O número de planos inválidos.

Parâmetros

Parâmetro	Descrição
sql_hash	O ID sql_hash da instrução SQL gerenciada do plano.
plan_hash	O ID plan_hash do plano gerenciado. Use NULL como média de todos os planos para o mesmo valor de ID sql_hash.
action	A ação que a função deve realizar em planos inválidos. Entre os valores de string válidos estão os seguintes. O uso de maiúsculas ou minúsculas não importa. 'disable' – todo plano inválido é desabilitado. 'delete' – todo plano inválido é excluído. 'update_plan_hash' – Atualiza o plan_hash ID para planos que não podem ser reproduzidos de forma exata. Ele também permite que você corrija um plano reescrevendo o SQL. Depois, você pode registrar o plano bom como um plano Approved para o SQL original. NULL – a função simplesmente retorna o número de planos inválidos. Nenhuma outra ação é realizada. '' – uma string vazia produz uma mensagem que indica o número de planos válidos e inválidos. Todos os outros valores são tratados como strings vazias.

Observações de uso

Use a forma validate_plans(action) a fim de validar todos os planos gerenciados para todas as instruções gerenciadas em toda a exibição apg_plan_mgmt.dba_plans.

Use a forma validate_plans(sql_hash, plan_hash, action) para validar um plano gerenciado especificado com plan_hash, para uma instrução gerenciada especificada com sql_hash.

Use a forma validate_plans(sql_hash, NULL, action) a fim de validar todos os planos gerenciados para a instrução gerenciada especificada com sql_hash.