Informazioni di riferimento sulle funzioni per la gestione del piano di query Aurora PostgreSQL - Amazon Aurora
copy_outlinedelete_planevolve_plan_baselinesget_explain_planplan_last_usedreloadset_plan_enabledset_plan_statusupdate_plans_last_usedvalidate_plans

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Informazioni di riferimento sulle funzioni per la gestione del piano di query Aurora PostgreSQL

L'estensione apg_plan_mgmt fornisce le seguenti funzioni.

apg_plan_mgmt.copy_outline

Copia un determinato hash e una struttura del piano SQL in un hash e una struttura del piano SQL di destinazione, sovrascrivendo così l'hash e la struttura del piano di destinazione. Questa funzione è disponibile in apg_plan_mgmt 2.3 e versioni successive.

Sintassi

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

Restituisce 0 quando la copia ha esito positivo. Genera eccezioni per gli input non validi.

Parametri

Parametro Descrizione
source_sql_hash L'ID sql_hash associato al plan_hash da copiare nella query di destinazione.
source_plan_hash L'ID plan_hash da copiare nella query di destinazione.
target_sql_hash L'ID sql_hash della query da aggiornare con l'hash e la struttura del piano di origine.
target_plan_hash L'ID plan_hash della query da aggiornare con l'hash e la struttura del piano di origine.
force_update_target_plan_hash (Facoltativo) L'target_plan_hashID della query viene aggiornato anche se il piano sorgente non è riproducibile per. target_sql_hash Se impostata su true, la funzione può essere utilizzata per copiare i piani tra schemi in cui i nomi delle relazioni e le colonne sono coerenti.

Note per l'utilizzo

Questa funzione consente di copiare un hash e una struttura del piano che utilizza i suggerimenti per altre dichiarazioni simili e quindi evita la necessità di usare istruzioni di suggerimento in linea ad ogni occorrenza nelle istruzioni di destinazione. Se la query di destinazione aggiornata genera un piano non valido, questa funzione restituisce un errore ed esegue il rollback del tentativo di aggiornamento.

apg_plan_mgmt.delete_plan

Elimina un piano gestito.

Sintassi

apg_plan_mgmt.delete_plan(
    sql_hash,
    plan_hash
)
Valore restituito

Restituisce 0 se l'eliminazione ha esito positivo o -1 se l'eliminazione non riesce.

Parametri

Parametro Descrizione
sql_hash L'ID sql_hash dell'istruzione SQL gestita del piano.
plan_hash L'ID plan_hash del piano gestito.

apg_plan_mgmt.evolve_plan_baselines

Verifica se un piano già approvato è più veloce o se un piano identificato dall'ottimizzatore di query come piano a costo minimo è più veloce.

Sintassi

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

Valore restituito

Il numero di piani che non sono più veloci del miglior piano approvato.

Parametri

Parametro Descrizione
sql_hash L'ID sql_hash dell'istruzione SQL gestita del piano.
plan_hash L'ID plan_hash del piano gestito. Utilizza NULL per indicare tutti i piani che hanno lo stesso valore di ID sql_hash.
min_speedup_factor

Il fattore di velocità minima indica quante volte un piano deve essere più veloce per essere approvato rispetto al migliore dei piani già approvati In alternativa, questo fattore può corrispondere quante volte deve essere più lento per essere rifiutato o disabilitato.

Questo è un valore float positivo.
action

L'azione che deve essere eseguita dalla funzione. I valori validi includono i seguenti. Non c'è distinzione tra lettere maiuscole e minuscole.

  • 'disable' – Disabilita ogni piano corrispondente che non soddisfa il fattore di accelerazione minimo.

  • 'approve' – Abilita ogni piano corrispondente che soddisfa il fattore di accelerazione minimo e imposta lo stato su approved.

  • 'reject' – Per ogni piano corrispondente che non soddisfa il fattore di accelerazione minimo, imposta lo stato su rejected.

  • NULL – La funzione restituisce semplicemente il numero di piani che non apportano alcun beneficio in termini di prestazioni poiché non soddisfano il fattore di accelerazione minimo.

Note per l'utilizzo

Imposta i piani specificati su approvato, rifiutato o disabilitato in base al fatto che la pianificazione più il tempo di esecuzione sia più veloce del migliore piano approvato da un fattore che puoi impostare. Il parametro action può essere impostato su 'approve' o 'reject' per approvare o rifiutare automaticamente un piano che soddisfa i criteri di prestazione. In alternativa, potrebbe essere impostato su '' (stringa vuota) per eseguire l'esperimento sulle prestazioni e produrre un report, senza intraprendere alcuna azione.

Puoi evitare di rieseguire inutilmente la funzione apg_plan_mgmt.evolve_plan_baselines per un piano su cui è stata eseguita di recente. Per farlo, limita i piani solo a quelli creati di recente e non ancora approvati. In alternativa, puoi evitare di eseguire la funzione apg_plan_mgmt.evolve_plan_baselines su qualsiasi piano approvato che abbia un timestamp recente last_verified.

Conduci un esperimento delle prestazioni per confrontare la pianificazione più il tempo di esecuzione di ciascun piano rispetto agli altri piani nella baseline. In alcuni casi, esiste un solo piano per un'istruzione e il piano è approvato. In tal caso, confronta la pianificazione più il tempo di esecuzione del piano con la pianificazione più il tempo di esecuzione dell'utilizzo di nessun piano.

Il vantaggio (o lo svantaggio) incrementale di ciascun piano è registrato nella visualizzazione apg_plan_mgmt.dba_plans nella colonna total_time_benefit_ms. Quando questo valore è positivo, c'è un vantaggio misurabile in termini di prestazioni per includere questo piano nella baseline.

Oltre a raccogliere i tempi di pianificazione ed esecuzione di ogni piano candidato, la colonna last_verified della visualizzazione apg_plan_mgmt.dba_plans viene aggiornata con il current_timestamp. È possibile utilizzare il time stamp last_verified per evitare di eseguire nuovamente questa funzione su un piano le cui prestazioni sono state verificate di recente.

apg_plan_mgmt.get_explain_plan

Genera il testo di una istruzione EXPLAIN per l'istruzione SQL specificata.

Sintassi

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

Restituisce le statistiche di runtime per le istruzioni SQL specificate. Utilizzare senza explainOptionList per restituire un piano EXPLAIN semplice.

Parametri

Parametro Descrizione
sql_hash L'ID sql_hash dell'istruzione SQL gestita del piano.
plan_hash L'ID plan_hash del piano gestito.
explainOptionList

Un elenco separato da virgole di opzioni di spiegazione. I valori validi includono 'analyze', 'verbose', 'buffers', 'hashes' e 'format json'. Se l'elenco di explainOptionList è NULL o una stringa vuota ("), questa funzione genera un’istruzione EXPLAIN, senza alcuna statistica.

Note per l'utilizzo

Per il explainOptionList, è possibile utilizzare una delle stesse opzioni che si utilizzerebbe con una istruzione EXPLAIN. L'ottimizzatore Aurora PostgreSQL concatena l'elenco delle opzioni fornite all'istruzione EXPLAIN.

apg_plan_mgmt.plan_last_used

Restituisce la data last_used del piano specificato dalla memoria condivisa.

Nota

Il valore nella memoria condivisa è sempre aggiornato sull'istanza database primaria nel cluster database. Il valore viene scaricato solo periodicamente nella colonna last_used della visualizzazione apg_plan_mgmt.dba_plans.

Sintassi

apg_plan_mgmt.plan_last_used(
    sql_hash,
    plan_hash
)
Valore restituito

Restituisce la data last_used.

Parametri

Parametro Descrizione
sql_hash L'ID sql_hash dell'istruzione SQL gestita del piano.
plan_hash L'ID plan_hash del piano gestito.

apg_plan_mgmt.reload

Ricarica i piani nella memoria condivisa dalla visualizzazione apg_plan_mgmt.dba_plans.

Sintassi

apg_plan_mgmt.reload()

Valore restituito

Nessuna.

Parametri

Nessuna.

Note per l'utilizzo

Chiama reload per le seguenti situazioni:

  • Usalo per aggiornare immediatamente la memoria condivisa di una replica di sola lettura, invece di aspettare che i nuovi piani si propaghino alla replica.

  • Usalo dopo l'importazione dei piani gestiti.

apg_plan_mgmt.set_plan_enabled

Abilita o disabilita un piano gestito.

Sintassi

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

Valore restituito

Restituisce 0 se l'impostazione ha esito positivo o -1 se l'impostazione non riesce.

Parametri

Parametro Descrizione
sql_hash L'ID sql_hash dell'istruzione SQL gestita del piano.
plan_hash L'ID plan_hash del piano gestito.
enabled

Valore booleano true o false:

  • Il valore true abilita il piano.

  • Il valore false disabilita il piano.

apg_plan_mgmt.set_plan_status

Impostare lo stato di un piano gestito su Approved, Unapproved, Rejected o Preferred.

Sintassi

apg_plan_mgmt.set_plan_status(
    sql_hash, 
    plan_hash, 
    status
)

Valore restituito

Restituisce 0 se l'impostazione ha esito positivo o -1 se l'impostazione non riesce.

Parametri

Parametro Descrizione
sql_hash L'ID sql_hash dell'istruzione SQL gestita del piano.
plan_hash L'ID plan_hash del piano gestito.
status

Stringa con uno dei seguenti valori:

  • 'Approved'

  • 'Unapproved'

  • 'Rejected'

  • 'Preferred'

Il caso utilizzato non ha importanza, tuttavia il valore di stato è impostato su maiuscole iniziali nella vista apg_plan_mgmt.dba_plans. Per ulteriori informazioni su questi valori, consulta status in Riferimento per la vista apg_plan_mgmt.dba_plans per Aurora PostgreSQL Compatible Edition.

apg_plan_mgmt.update_plans_last_used

Aggiorna immediatamente la tabella dei piani con la data last_used memorizzata nella memoria condivisa.

Sintassi

apg_plan_mgmt.update_plans_last_used()

Valore restituito

Nessuna.

Parametri

Nessuna.

Note per l'utilizzo

Eseguire una chiamata a update_plans_last_used per assicurarsi che le query contro la colonna dba_plans.last_used utilizzino le informazioni più aggiornate. Se il la data last_used non viene aggiornata immediatamente, un processo in background aggiorna la tabella dei piani con la data last_used una volta ogni ora (per impostazione predefinita).

Ad esempio, se un'istruzione con una certa sql_hash inizia a funzionare lentamente, è possibile determinare quali piani per quell'istruzione sono stati eseguiti dall'inizio della regressione delle prestazioni. Per fare ciò, innanzitutto svuotare i dati nella memoria condivisa su disco in modo che le date last_used siano correnti e quindi interroghino tutti i piani dell'istruzione sql_hash con la regressione delle prestazioni. Nella query, assicurati che la data last_used sia maggiore o uguale alla data in cui è iniziata la regressione delle prestazioni. La query identifica il piano o l'insieme di piani che potrebbero essere responsabili della regressione delle prestazioni. È possibile utilizzare apg_plan_mgmt.get_explain_plan con explainOptionList impostato su verbose, hashes. È possibile utilizzare anche apg_plan_mgmt.evolve_plan_baselines per analizzare il piano e qualsiasi piano alternativo che potrebbe funzionare meglio.

La funzione update_plans_last_used ha un effetto solo sull'istanza database primaria del cluster database.

apg_plan_mgmt.validate_plans

Convalida che l'ottimizzatore può ancora ricreare piani. L'ottimizzatore convalida i piani Approved, Unapproved e Preferred, se il piano è abilitato o disabilitato. I piani Rejected non sono convalidati. Facoltativamente, puoi utilizzare la funzione apg_plan_mgmt.validate_plans per eliminare o disabilitare i piani non validi.

Sintassi

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

Valore restituito

Numero di piani non validi.

Parametri

Parametro Descrizione
sql_hash L'ID sql_hash dell'istruzione SQL gestita del piano.
plan_hash L'ID plan_hash del piano gestito. Utilizza NULL per indicare tutti i piani con lo stesso valore di ID sql_hash.
action

L'azione che deve essere eseguita dalla funzione per i piani non validi. I valori di stringa validi includono i seguenti: Non c'è distinzione tra lettere maiuscole e minuscole.

  • 'disable' – Ogni piano non valido è disabilitato.

  • 'delete' – Ogni piano non valido è eliminato.

  • 'update_plan_hash' – Aggiorna l'ID plan_hash per i piani che non possono essere riprodotti esattamente. Consente inoltre di correggere un piano riscrivendo l'SQL. Puoi registrare il piano buono come piano Approved per l'SQL di origine.

  • NULL – La funzione restituisce semplicemente il numero di piani non validi. Non vengono eseguite altre operazioni.

  • '' – Una stringa vuota genera un messaggio che indica il numero di piani validi e non validi.

Qualsiasi altro valore viene considerato come una stringa vuota.

Note per l'utilizzo

Usa il modulo validate_plans(action) per convalidare tutti i piani gestiti per tutte le istruzioni gestite nell'intera visualizzazione apg_plan_mgmt.dba_plans.

Usa il modulo validate_plans(sql_hash, plan_hash, action) per convalidare un piano gestito specificato con plan_hash, per un'istruzione gestita specificata con sql_hash.

Usa il modulo validate_plans(sql_hash, NULL, action) per convalidare tutti i piani gestiti per l'istruzione gestita specificata con sql_hash.