Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Benannte Hinweise erstellen und verwalten

Wenn Sie steuern möchten, wie der AlloyDB for PostgreSQL-Abfrageplaner Ausführungspläne generiert, ohne Ihre Anwendungsabfragen zu ändern, können Sie benannte Hinweise erstellen, prüfen, aufrufen, aktivieren, deaktivieren und löschen. Benannte Hinweise verknüpfen eine Abfrage mit einer Reihe von Hinweisen, die Details zum bevorzugten Ausführungsplan angeben. Wenn der Abfrageplaner einen Ausführungsplan für die zugehörige Abfrage generiert, wendet er die Hinweise an und wendet sie bei nachfolgenden Ausführungen der Abfrage automatisch wieder an. Sie können beispielsweise benannte Hints verwenden, um einen Indexscan anstelle eines sequenziellen Scans für eine Tabelle zu erzwingen oder eine bestimmte Join-Reihenfolge für mehrere Tabellen zu erzwingen.

Benannte Hints in AlloyDB unterstützen alle Hints aus der Open-Source-Erweiterung pg_hint_plan und die folgenden Hints für die spaltenbasierte Engine:

ColumnarScan(table): Erzwingt einen spaltenbasierten Scan der Tabelle.
NoColumnarScan(table): Deaktiviert einen spaltenbasierten Scan für die Tabelle.

Mit AlloyDB können Sie benannte Hinweise sowohl für parametrisierte als auch für nicht parametrisierte Abfragen erstellen, die in diesem Dokument als parametersensitive Abfragen bezeichnet werden.

Workflow

Die Verwendung benannter Hints umfasst die folgenden Schritte:

Identifizieren Sie die Abfrage, für die Sie benannte Hinweise erstellen möchten.
Erstellen Sie benannte Hinweise mit Hinweisen, die bei der nächsten Ausführung der Abfrage angewendet werden sollen.
Anwendung der benannten Hinweise prüfen.

Auf dieser Seite werden die folgende Tabelle und der folgende Index für Beispiele verwendet:

CREATE TABLE t(a INT, b INT);
CREATE INDEX t_idx1 ON t(a);

  DROP EXTENSION IF EXISTS google_auto_hints;

Wenn Sie die benannten Hinweise, die Sie mit einer früheren Version erstellt haben, weiterhin verwenden möchten, erstellen Sie sie neu. Folgen Sie dazu der Anleitung auf dieser Seite.

Hinweis

Aktivieren Sie die Funktion für benannte Hinweise auf Ihrer Instanz. Legen Sie das Flag alloydb.enable_named_hints auf on fest. Sie können dieses Flag auf serverweiter Ebene oder auf Sitzungsebene aktivieren. Um den durch die Verwendung dieser Funktion entstehenden Overhead zu minimieren, aktivieren Sie dieses Flag nur auf Sitzungsebene.

Weitere Informationen finden Sie unter Datenbank-Flags einer Instanz konfigurieren.

Hinweis: Wenn Sie denselben Abfrageplan auf Ihrer Lesepoolinstanz erzwingen möchten, aktivieren Sie die Funktion für benannte Hints auf der Lesepoolinstanz.

Führen Sie den Befehl show alloydb.enable_named_hints; aus, um zu prüfen, ob das Flag aktiviert ist. Wenn das Flag aktiviert ist, wird in der Ausgabe „on“ zurückgegeben.
Erstellen Sie für jede Datenbank, in der Sie benannte Hints verwenden möchten, eine Erweiterung in der Datenbank der primären AlloyDB-Instanz als alloydbsuperuser- oder postgres-Nutzer:
```
CREATE EXTENSION google_auto_hints CASCADE;
```

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen (Identity and Access Management) zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwalten von benannten Hinweisen benötigen:

Rolle alloydbsuperuser

Die Standardberechtigung erlaubt nur Nutzern mit der Rolle alloydbsuperuser, benannte Hints zu erstellen. Sie können die Schreibberechtigung aber auch anderen Nutzern oder Rollen der Datenbank erteilen, damit diese benannte Hints erstellen können.

GRANT INSERT,DELETE,UPDATE ON hint_plan.plan_patches, hint_plan.hints TO role_name;
GRANT USAGE ON SEQUENCE hint_plan.hints_id_seq, hint_plan.plan_patches_id_seq TO role_name;

Abfrage identifizieren

Anhand der Abfrage-ID können Sie die Abfrage identifizieren, deren Standardplan optimiert werden muss. Die Abfrage-ID ist verfügbar, nachdem die Abfrage mindestens einmal ausgeführt wurde.

Verwenden Sie die folgenden Methoden, um die Abfrage-ID zu ermitteln:

Führen Sie den Befehl EXPLAIN (VERBOSE) aus, wie im folgenden Beispiel gezeigt:

EXPLAIN (VERBOSE) SELECT * FROM t WHERE a = 99;
                        QUERY PLAN
----------------------------------------------------------
Seq Scan on public.t  (cost=0.00..38.25 rows=11 width=8)
  Output: a, b
  Filter: (t.a = 99)
Query Identifier: -6875839275481643436

In der Ausgabe lautet die Abfrage-ID -6875839275481643436.

Fragen Sie die Ansicht pg_stat_statements ab.

Wenn Sie die Erweiterung pg_stat_statements aktiviert haben, können Sie die Abfrage-ID durch Abfragen der Ansicht pg_stat_statements ermitteln, wie im folgenden Beispiel gezeigt:
```
select query, queryid from pg_stat_statements;
```

Benannte Hinweise erstellen

Verwenden Sie zum Erstellen benannter Hinweise die Funktion google_create_named_hints(), die eine Verknüpfung zwischen der Abfrage und den Hinweisen in der Datenbank erstellt.

SELECT google_create_named_hints(
HINTS_NAME=>'HINTS_NAME',
SQL_ID=>QUERY_ID,
SQL_TEXT=>QUERY_TEXT,
APPLICATION_NAME=>'APPLICATION_NAME',
HINTS=>'HINTS',
DISABLED=>DISABLED);

Ersetzen Sie Folgendes:

HINTS_NAME: ein Name für die benannten Hinweise. Dieser muss innerhalb der Datenbank eindeutig sein.
SQL_ID (optional): Abfrage-ID der Abfrage, für die Sie die benannten Hinweise erstellen.

Sie können entweder die Abfrage-ID oder den Abfragetext (den Parameter SQL_TEXT) verwenden, um benannte Hinweise zu erstellen. Wir empfehlen jedoch, die Abfrage-ID zum Erstellen benannter Hinweise zu verwenden, da AlloyDB den normalisierten Abfragetext automatisch anhand der Abfrage-ID findet.
SQL_TEXT (optional): Abfragetext der Abfrage, für die Sie die benannten Hinweise erstellen.

Wenn Sie den Abfragetext verwenden, muss der Text mit der beabsichtigten Abfrage übereinstimmen, mit Ausnahme der Literal- und Konstantenwerte in der Abfrage. Bei Abweichungen, einschließlich Groß-/Kleinschreibung, werden die benannten Hinweise möglicherweise nicht angewendet. Informationen zum Erstellen benannter Hinweise für Abfragen mit Literalen und Konstanten finden Sie unter Parametersensitive benannte Hinweise erstellen.
APPLICATION_NAME (optional): Name der Sitzungsclientanwendung, für die Sie die benannten Hinweise verwenden möchten. Mit einem leeren String können Sie die benannten Hinweise auf die Abfrage anwenden, unabhängig davon, welche Clientanwendung die Abfrage ausgibt.
HINTS: Eine durch Leerzeichen getrennte Liste der Hinweise für die Abfrage.
DISABLED (optional): BOOL. Wenn TRUE, werden die benannten Hinweise anfänglich als deaktiviert erstellt.

Beispiel:

SELECT google_create_named_hints(
HINTS_NAME=>'my_hint1',
SQL_ID=>-6875839275481643436,
SQL_TEXT=>NULL,
APPLICATION_NAME=>'',
HINTS=>'IndexScan(t)',
DISABLED=>NULL);

Mit dieser Abfrage wird ein benannter Hinweis mit dem Namen my_hint1 erstellt. Der Hinweis IndexScan(t) wird vom Planer angewendet, um bei der nächsten Ausführung dieser Beispielabfrage einen Indexscan für die Tabelle t zu erzwingen.

Nachdem Sie benannte Hinweise erstellt haben, können Sie mit google_named_hints_view prüfen, ob die benannten Hinweise erstellt wurden, wie im folgenden Beispiel gezeigt:

postgres=>\x
postgres=>select * from google_named_hints_view limit 1;
-[ RECORD 1 ]-----+-----------------------------
hints_name | my_hint1
sql_id | -6875839275481643436
id | 9
query_string | SELECT * FROM t WHERE a = ?;
application_name |
hints | IndexScan(t)
disabled | f

Nachdem die benannten Hinweise auf der primären Instanz erstellt wurden, werden sie automatisch auf die zugehörigen Abfragen in der Lesepoolinstanz angewendet, sofern Sie die Funktion für benannte Hinweise auch in der Lesepoolinstanz aktiviert haben.

Parameterabhängige benannte Hinweise erstellen

Wenn benannte Hinweise für eine Abfrage erstellt werden, wird der zugehörige Abfragetext standardmäßig normalisiert. Dazu werden alle Literal- und Konstantenwerte im Abfragetext durch einen Parametermarkierung wie ? ersetzt. Die benannten Hinweise werden dann für diese normalisierte Abfrage verwendet, auch wenn der Parameter-Marker einen anderen Wert hat.

Wenn Sie beispielsweise die folgende Abfrage ausführen, kann eine andere Abfrage wie SELECT * FROM t WHERE a = 99; die benannten Hinweise my_hint2 standardmäßig verwenden.

SELECT google_create_named_hints(
  HINTS_NAME=>'my_hint2',
  SQL_ID=>NULL,
  SQL_TEXT=>'SELECT * FROM t WHERE a = ?;',
  APPLICATION_NAME=>'',
  HINTS=>'SeqScan(t)',
  DISABLED=>NULL);

Anschließend kann eine Abfrage wie SELECT * FROM t WHERE a = 99; standardmäßig die benannten Hinweise my_hint2 verwenden.

Mit AlloyDB können Sie auch benannte Hinweise für nicht parametrisierte Abfragetexte erstellen, bei denen jeder Literal- und Konstantenwert im Abfragetext beim Abgleich von Abfragen von Bedeutung ist.

Wenn Sie parameterabhängige benannte Hinweise anwenden, werden zwei Abfragen, die sich nur in den entsprechenden Literal- oder Konstantenwerten unterscheiden, ebenfalls als unterschiedlich betrachtet. Wenn Sie Pläne für beide Abfragen erzwingen möchten, müssen Sie für jede Abfrage separate benannte Hinweise erstellen. Sie können jedoch unterschiedliche Hints für die beiden benannten Hints verwenden.

Wenn Sie parameterabhängige benannte Hinweise erstellen möchten, setzen Sie den Parameter SENSITIVE_TO_PARAM der Funktion google_create_named_hints() auf TRUE, wie im folgenden Beispiel gezeigt:

SELECT google_create_named_hints(
HINTS_NAME=>'my_hint3',
SQL_ID=>NULL,
SQL_TEXT=>'SELECT * FROM t WHERE a = 88;',
APPLICATION_NAME=>'',
HINTS=>'IndexScan(t)',
DISABLED=>NULL,
SENSITIVE_TO_PARAM=>TRUE);

Die Abfrage SELECT * FROM t WHERE a = 99; kann die benannten Hinweise my_hint3 nicht verwenden, da der Literalwert „99“ nicht mit „88“ übereinstimmt.

Beachten Sie bei der Verwendung von parameterabhängigen benannten Hinweisen Folgendes:

Parametersensitive benannte Hinweise unterstützen keine Mischung aus Literal- und Konstantenwerten und Parametermarkierungen im Abfragetext.
Wenn Sie parametersensitive benannte Hinweise und einen standardmäßigen benannten Hinweis für dieselbe Abfrage erstellen, werden die parametersensitiven benannten Hinweise den standardmäßigen benannten Hinweisen vorgezogen.
Wenn Sie die Abfrage-ID verwenden möchten, um parameterabhängige benannte Hinweise zu erstellen, muss die Abfrage in der aktuellen Sitzung ausgeführt worden sein. Die Parameterwerte aus der letzten Ausführung (in der aktuellen Sitzung) werden verwendet, um die benannten Hints zu erstellen.

Anwendung der benannten Hints prüfen

Nachdem Sie die benannten Hinweise erstellt haben, können Sie mit den folgenden Methoden prüfen, ob der Abfrageplan entsprechend erzwungen wird.

Verwenden Sie den Befehl EXPLAIN oder EXPLAIN (ANALYZE).

Wenn Sie die Hinweise sehen möchten, die der Planer anzuwenden versucht, können Sie die folgenden Flags auf Sitzungsebene festlegen, bevor Sie den Befehl EXPLAIN ausführen:
```
SET pg_hint_plan.debug_print = ON;
SET client_min_messages = LOG;
```
Verwenden Sie die Erweiterung auto_explain.

Benannte Hinweise verwalten

Mit AlloyDB können Sie benannte Hints ansehen, aktivieren, deaktivieren und löschen.

Benannte Hinweise ansehen

Wenn Sie vorhandene benannte Hinweise aufrufen möchten, verwenden Sie die Funktion google_named_hints_view, wie im folgenden Beispiel gezeigt:

postgres=>\x
postgres=>select * from google_named_hints_view limit 1;
-[ RECORD 1 ]-----+-----------------------------
hints_name | my_hint1
sql_id | -6875839275481643436
id | 9
query_string | SELECT * FROM t WHERE a = ?;
application_name |
hints | IndexScan(t)
disabled | f

Benannte Hinweise aktivieren

Mit der Funktion google_enable_named_hints(HINTS_NAME) können Sie vorhandene benannte Hinweise aktivieren. Standardmäßig sind benannte Hinweise aktiviert, wenn Sie sie erstellen.

Wenn Sie beispielsweise die zuvor deaktivierten benannten Hinweise my_hint1 aus der Datenbank wieder aktivieren möchten, führen Sie die folgende Funktion aus:

SELECT google_enable_named_hints('my_hint1');

Benannte Hints deaktivieren

Mit der Funktion google_disable_named_hints(HINTS_NAME) können Sie vorhandene benannte Hinweise deaktivieren.

Wenn Sie beispielsweise die benannten Beispiel-Hints my_hint1 aus der Datenbank löschen möchten, führen Sie die folgende Funktion aus:

SELECT google_disable_named_hints('my_hint1');

Benannte Hinweise löschen

Verwenden Sie die Funktion google_delete_named_hints(HINTS_NAME), um benannte Hinweise zu löschen.