# 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. **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 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\$1sql\$1hash | O ID sql\$1hash associado ao plan\$1hash a ser copiado na consulta de destino. | | source\$1plan\$1hash | O ID plan\$1hash a ser copiado na consulta de destino. | | target\$1sql\$1hash | O ID sql\$1hash da consulta a ser atualizada com o hash e o esboço do plano de origem. | | target\$1plan\$1hash | O ID plan\$1hash da consulta a ser atualizada com o hash e o esboço do plano de origem. | | force\$1update\$1target\$1plan\$1hash | (Opcional) O ID target\$1plan\$1hash da consulta é atualizado mesmo que o plano de origem não seja reproduzível para o target\$1sql\$1hash. 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\$1plan\$1mgmt.delete\$1plan 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\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. | | plan\$1hash | O ID plan\$1hash do plano gerenciado. | ## apg\$1plan\$1mgmt.evolve\$1plan\$1baselines 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\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. | | plan\$1hash | O ID plan\$1hash do plano gerenciado. Use NULL como média de todos os planos que tenham o mesmo valor de ID sql\$1hash. | | min\$1speedup\$1factor | 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) | ** 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\$1plan\$1mgmt.get\$1explain\$1plan 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\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. | | plan\$1hash | O ID plan\$1hash 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\$1plan\$1mgmt.plan\$1last\$1used 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\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. | | plan\$1hash | O ID plan\$1hash do plano gerenciado. | ## apg\$1plan\$1mgmt.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\$1plan\$1mgmt.set\$1plan\$1enabled 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\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. | | plan\$1hash | O ID plan\$1hash do plano gerenciado. | | enabled | Valores boolianos de verdadeiro ou falso: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) | ## apg\$1plan\$1mgmt.set\$1plan\$1status 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\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. | | plan\$1hash | O ID plan\$1hash do plano gerenciado. | | status | Uma string com um dos seguintes valores: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) 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\$1plan\$1mgmt.dba\$1plans da edição compatível do Aurora PostgreSQL](AuroraPostgreSQL.Optimize.dba_plans_view_Reference.md). | ## apg\$1plan\$1mgmt.update\$1plans\$1last\$1used 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\$1plan\$1mgmt.validate\$1plans 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\$1hash | O ID sql\$1hash da instrução SQL gerenciada do plano. | | plan\$1hash | O ID plan\$1hash do plano gerenciado. Use NULL como média de todos os planos para o mesmo valor de ID sql\$1hash. | | 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. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) 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`.