Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Référence de la fonction pour la gestion du plan de requête Aurora PostgreSQL L’extension `apg_plan_mgmt` fournit les fonctions suivantes. **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 Copiez un hachage et un contour de plan SQL donnés vers un hachage et un contour de plan SQL cible, écrasant ainsi le hachage et le contour de plan de la cible. Cette fonction est disponible dans `apg_plan_mgmt` versions 2.3 et ultérieures. **Syntaxe** ``` apg_plan_mgmt.copy_outline( source_sql_hash, source_plan_hash, target_sql_hash, target_plan_hash, force_update_target_plan_hash ) ``` **Valeur renvoyée** Renvoie 0 lorsque la copie est réussie. Déclenche des exceptions pour les entrées non valides. **Paramètres** **** | Paramètre | Description | | --- | --- | | source\$1sql\$1hash | L’ID sql\$1hash associé à la valeur plan\$1hash à copier vers la requête cible. | | source\$1plan\$1hash | L’ID plan\$1hash à copier vers la requête cible. | | target\$1sql\$1hash | L’ID sql\$1hash de la requête à mettre à jour avec le hachage et le plan source. | | target\$1plan\$1hash | L’ID plan\$1hash de la requête à mettre à jour avec le hachage et le plan source. | | force\$1update\$1target\$1plan\$1hash | (Facultatif) L’ID target\$1plan\$1hash de la requête est mis à jour même si le plan source n’est pas reproductible pour target\$1sql\$1hash. Lorsqu’elle est définie sur true, cette fonction peut être utilisée pour copier des plans dans des schémas où les noms des relations et les colonnes sont cohérents. | **Notes d’utilisation** Cette fonction vous permet de copier un hachage de plan et un contour de plan qui utilise des astuces dans d’autres instructions similaires, ce qui vous évite d’avoir à utiliser des instructions d’astuces en ligne à chaque occurrence dans les instructions cibles. Si la requête cible mise à jour résulte en un plan invalide, cette fonction soulève une erreur et annule la tentative de mise à jour. ## apg\$1plan\$1mgmt.delete\$1plan Supprimez un plan géré. **Syntaxe** ``` apg_plan_mgmt.delete_plan( sql_hash, plan_hash ) ``` **Valeur renvoyée** Renvoie 0 si la suppression a réussi ou -1 si elle a échoué. **Paramètres** **** | Paramètre | Description | | --- | --- | | sql\$1hash | ID sql\$1hash de l’instruction SQL gérée du plan. | | plan\$1hash | ID plan\$1hash du plan géré. | ## apg\$1plan\$1mgmt.evolve\$1plan\$1baselines Vérifie si un plan déjà approuvé est plus rapide ou si un plan identifié par l’optimiseur de requêtes en tant que plan à coût minimal est plus rapide. **Syntaxe** ``` apg_plan_mgmt.evolve_plan_baselines( sql_hash, plan_hash, min_speedup_factor, action ) ``` **Valeur renvoyée** Nombre de plans qui n’étaient pas plus rapides que le meilleur plan approuvé. **Paramètres** **** | Paramètre | Description | | --- | --- | | sql\$1hash | ID sql\$1hash de l’instruction SQL gérée du plan. | | plan\$1hash | ID plan\$1hash du plan géré. Utilisez NULL pour indiquer que tous les plans ont la même valeur d’ID sql\$1hash. | | min\$1speedup\$1factor | Le *facteur de montée en charge minimum* est le nombre de fois qu’un plan doit être plus rapide que le meilleur des plans déjà approuvés pour être approuvé. Sinon, ce facteur peut être le nombre de fois qu’un plan doit être plus lent pour être rejeté ou désactivé. Il s’agit d’une valeur flottante positive. | | action | Action que la fonction doit exécuter. Les valeurs valides sont notamment les suivantes. La casse n’a pas d’importance. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) | **Notes d’utilisation** Définissez les plans spécifiés sur approuvé, rejeté ou désactivé selon que la durée de planification et d’exécution est plus rapide que celle du meilleur plan approuvé selon un facteur que vous pouvez définir. Le paramètre d’action peut être défini sur `'approve'` ou `'reject'` pour approuver ou rejeter automatiquement un plan qui respecte les critères de performance. Vous pouvez également le définir sur ’’ (chaîne vide) pour tester les performances et produire un rapport, mais sans effectuer d’action. Vous pouvez inutilement éviter d’exécuter à nouveau la fonction `apg_plan_mgmt.evolve_plan_baselines` pour un plan sur lequel elle a été exécutée récemment. À cette fin, limitez les plans aux plans non approuvés créés récemment. Vous pouvez également éviter d’exécuter la fonction `apg_plan_mgmt.evolve_plan_baselines` sur un plan approuvé qui a reçu un horodatage `last_verified` récent. Effectuez un test des performances pour comparer la durée de planification et d’exécution de chaque plan par rapport à d’autres plans de la référence. Dans certains cas, il n’existe qu’un seul plan pour une instruction et ce plan est approuvé. Dans ce cas, comparez la durée de planification et la durée d’exécution du plan à ce que seraient ces durées si aucun plan n’était utilisé. L’avantage (ou le désavantage) incrémentiel de chaque plan est enregistré dans la vue `apg_plan_mgmt.dba_plans` de la colonne `total_time_benefit_ms`. Lorsque cette valeur est positive, il y a un avantage mesurable en termes de performances à inclure ce plan dans la référence. En plus de consigner la durée de planification et d’exécution de chaque plan candidat, la colonne `last_verified` de la vue `apg_plan_mgmt.dba_plans` est mise à jour avec `current_timestamp`. L’horodatage `last_verified` peut être utilisé pour éviter d’exécuter à nouveau cette fonction sur un plan dont les performances ont récemment été vérifiées. ## apg\$1plan\$1mgmt.get\$1explain\$1plan Génère le texte d’une instruction `EXPLAIN` pour l’instruction SQL spécifiée. **Syntaxe** ``` apg_plan_mgmt.get_explain_plan( sql_hash, plan_hash, [explainOptionList] ) ``` **Valeur renvoyée** Renvoie des statistiques d’exécution pour les instructions SQL spécifiées. Utiliser sans `explainOptionList` pour renvoyer un plan `EXPLAIN` simple. **Paramètres** **** | Paramètre | Description | | --- | --- | | sql\$1hash | ID sql\$1hash de l’instruction SQL gérée du plan. | | plan\$1hash | ID plan\$1hash du plan géré. | | explainOptionList | Liste séparée par des virgules d’options d’explication. Les valeurs valides incluent `'analyze'`, `'verbose'`, `'buffers'`, `'hashes'` et `'format json'`. Si la liste des `explainOptionList` est NULL ou une chaîne vide (’’), cette fonction génère une instruction `EXPLAIN`, sans aucune statistique. | **Notes d’utilisation** Pour le `explainOptionList`, vous pouvez utiliser l’une des mêmes options que vous utiliseriez avec une instruction `EXPLAIN`. L’optimiseur Aurora PostgreSQL concatène la liste des options que vous fournissez à l’instruction `EXPLAIN`. ## apg\$1plan\$1mgmt.plan\$1last\$1used Renvoie la date `last_used` du plan spécifié depuis la mémoire partagée. **Note** La valeur de la mémoire partagée est toujours à jour sur l’instance de base de données principale du cluster de bases de données. La valeur est uniquement vidée vers périodiquement dans la colonne `last_used` de la vue `apg_plan_mgmt.dba_plans`. **Syntaxe** ``` apg_plan_mgmt.plan_last_used( sql_hash, plan_hash ) ``` **Valeur renvoyée** Renvoie la date `last_used`. **Paramètres** **** | Paramètre | Description | | --- | --- | | sql\$1hash | ID sql\$1hash de l’instruction SQL gérée du plan. | | plan\$1hash | ID plan\$1hash du plan géré. | ## apg\$1plan\$1mgmt.reload Recharge les plans dans la mémoire partagée depuis la vue `apg_plan_mgmt.dba_plans`. **Syntaxe** ``` apg_plan_mgmt.reload() ``` **Valeur renvoyée** Aucun. **Paramètres** Aucune. **Notes d’utilisation** Appelez `reload` dans les cas suivants : + Utilisez-le pour rafraîchir immédiatement la mémoire partagée d’un réplica en lecture seule, plutôt que d’attendre que les nouveaux plans se propagent au réplica. + Utilisez-le après l’importation de plans gérés. ## apg\$1plan\$1mgmt.set\$1plan\$1enabled Activez ou désactivez un plan géré. **Syntaxe** ``` apg_plan_mgmt.set_plan_enabled( sql_hash, plan_hash, [true | false] ) ``` **Valeur renvoyée** Renvoie 0 si le paramétrage a réussi ou -1 s’il a échoué. **Paramètres** **** | Paramètre | Description | | --- | --- | | sql\$1hash | ID sql\$1hash de l’instruction SQL gérée du plan. | | plan\$1hash | ID plan\$1hash du plan géré. | | enabled | Valeur booléenne true ou false : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) | ## apg\$1plan\$1mgmt.set\$1plan\$1status Définissez le statut d’un plan géré sur `Approved`, `Unapproved`, `Rejected` ou `Preferred`. **Syntaxe** ``` apg_plan_mgmt.set_plan_status( sql_hash, plan_hash, status ) ``` **Valeur renvoyée** Renvoie 0 si le paramétrage a réussi ou -1 s’il a échoué. **Paramètres** **** | Paramètre | Description | | --- | --- | | sql\$1hash | ID sql\$1hash de l’instruction SQL gérée du plan. | | plan\$1hash | ID plan\$1hash du plan géré. | | status | Chaîne dotée de l’une des valeurs suivantes : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) La casse que vous utilisez n’a pas d’importance, mais la valeur du statut est définie avec des capitales initiales dans la vue `apg_plan_mgmt.dba_plans`. Pour plus d’informations sur ces valeurs, consultez la rubrique `status` de la section [Référence pour la vue apg\$1plan\$1mgmt.dba\$1plans pour l’édition compatible avec Aurora PostgreSQL](AuroraPostgreSQL.Optimize.dba_plans_view_Reference.md). | ## apg\$1plan\$1mgmt.update\$1plans\$1last\$1used Met immédiatement à jour le tableau des plans avec la date `last_used` stockée dans la mémoire partagée. **Syntaxe** ``` apg_plan_mgmt.update_plans_last_used() ``` **Valeur renvoyée** Aucun. **Paramètres** Aucune. **Notes d’utilisation** Appelez `update_plans_last_used` pour veiller à ce que les requêtes de la colonne `dba_plans.last_used` utilise les informations les plus récentes. Si la date `last_used` n’est pas immédiatement mise à jour, un processus en arrière-plan met à jour la table des plans avec la date `last_used` une fois par heure (par défaut). Par exemple, si une instruction avec un certain `sql_hash` commence à s’exécuter lentement, vous pouvez déterminer quels plans de cette instruction ont été exécutés depuis le début de la régression des performances. Pour ce faire, commencez par vider les données de la mémoire partagée sur le disque afin que les dates `last_used` soient à jour, puis interrogez tous les plans du `sql_hash` de l’instruction présentant la régression des performances. Dans la requête, assurez-vous que le date `last_used` est supérieure ou égale à la date à laquelle la régression des performances a commencé. La requête identifie le plan ou l’ensemble de plans susceptibles d’être responsables de la régression des performances. Vous pouvez utiliser `apg_plan_mgmt.get_explain_plan` avec `explainOptionList` défini sur `verbose, hashes`. Vous pouvez également utiliser `apg_plan_mgmt.evolve_plan_baselines` pour analyser le plan et tous les autres plans susceptibles de s’avérer plus performants. La fonction `update_plans_last_used` affecte uniquement l’instance de base de données principale du cluster de bases de données. ## apg\$1plan\$1mgmt.validate\$1plans Validez le fait que l’optimiseur peut toujours recréer des plans. L’optimiseur valide les plans `Approved`, `Unapproved` et `Preferred`, que les plans soient activés ou désactivés. Les plans `Rejected` ne sont pas validés. Vous pouvez également utiliser la fonction `apg_plan_mgmt.validate_plans` pour supprimer ou désactiver des plans non valides. **Syntaxe** ``` apg_plan_mgmt.validate_plans( sql_hash, plan_hash, action) apg_plan_mgmt.validate_plans( action) ``` **Valeur renvoyée** Nombre de plans non valides. **Paramètres** **** | Paramètre | Description | | --- | --- | | sql\$1hash | ID sql\$1hash de l’instruction SQL gérée du plan. | | plan\$1hash | ID plan\$1hash du plan géré. Utilisez NULL pour inclure tous les plans ayant la même valeur d’ID sql\$1hash. | | action | Action que la fonction doit exécuter pour les plans non valides. Les valeurs de chaînes valides sont notamment les suivantes. La casse n’a pas d’importance. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Optimize.Functions.html) Toute autre valeur est traitée comme une chaîne vide. | **Notes d’utilisation** Utilisez le formulaire `validate_plans(action)` pour valider tous les plans gérés pour toutes les instructions gérées dans la vue `apg_plan_mgmt.dba_plans` complète. Utilisez le formulaire `validate_plans(sql_hash, plan_hash, action)` pour valider un plan géré spécifié avec `plan_hash` pour une instruction gérée spécifiée avec `sql_hash`. Utilisez le formulaire `validate_plans(sql_hash, NULL, action)` pour valider tous les plans gérés pour l’instruction gérée spécifiée avec `sql_hash`.