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

Benannte Hinweise erstellen und verwalten

Auf dieser Seite wird beschrieben, wie Sie benannte Hinweise in AlloyDB for PostgreSQL erstellen und verwalten.

Benannte Hinweise sind eine Verknüpfung zwischen einer Abfrage und einer Reihe von Hinweisen, mit denen Sie die Details des Abfrageplans angeben können. Ein Hinweis enthält zusätzliche Informationen zum bevorzugten endgültigen Ausführungsplan für die Abfrage. Wenn Sie beispielsweise eine Tabelle in der Abfrage scannen, verwenden Sie einen Indexscan anstelle anderer Arten von Scans wie einen sequenziellen Scan.

Um die Auswahl des endgültigen Plans innerhalb der Spezifikation der Hinweise zu beschränken, wendet der Abfrageplaner die Hinweise zuerst auf die Abfrage an, während er den Ausführungsplan generiert. Die Hinweise werden dann automatisch angewendet, wenn die Abfrage anschließend ausgegeben wird. Mit diesem Ansatz können Sie verschiedene Abfragepläne vom Planer erzwingen. Sie können beispielsweise Hinweise verwenden, um einen Indexscan für bestimmte Tabellen zu erzwingen oder eine bestimmte Join-Reihenfolge zwischen mehreren Tabellen zu erzwingen.

Die benannten Hinweise von AlloyDB unterstützen alle Hinweise aus der Open-Source-pg_hint_planErweiterung.

Außerdem unterstützt AlloyDB die folgenden Hinweise für die spaltenbasierte Engine:

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

In AlloyDB können Sie benannte Hinweise sowohl für parametrisierte als auch für nicht parametrisierte Abfragen erstellen. Auf dieser Seite werden nicht parametrisierte Abfragen als parameterabhängige Abfragen bezeichnet.

Workflow

Die Verwendung benannter Hinweise 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.
Prüfen Sie die Anwendung der benannten Hinweise.

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 noch einmal. Folgen Sie dazu der Anleitung auf dieser Seite.

Hinweis

Aktivieren Sie das Feature für benannte Hinweise in Ihrer Instanz. Legen Sie das Flag alloydb.enable_named_hints auf on fest. Sie können dieses Flag auf Server- oder Sitzungsebene aktivieren. Um den Mehraufwand zu minimieren, der durch die Verwendung dieses Features entstehen kann, aktivieren Sie dieses Flag nur auf Sitzungsebene.

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

Hinweis: Wenn Sie denselben Abfrageplan für Ihre Lesepoolinstanz erzwingen möchten, aktivieren Sie das Feature für benannte Hinweise in 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 Hinweise verwenden möchten, eine Erweiterung in der Datenbank von der primären AlloyDB-Instanz als der alloydbsuperuser oder der 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

Mit der Standardberechtigung kann nur der Nutzer mit der Rolle alloydbsuperuser benannte Hinweise erstellen. Optional können Sie anderen Nutzern oder Rollen der Datenbank die Schreibberechtigung erteilen, damit sie benannte Hinweise 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

Mit der Abfrage-ID können Sie die Abfrage identifizieren, deren Standardplan optimiert werden muss. Die Abfrage-ID ist nach mindestens einer Ausführung der Abfrage verfügbar.

Verwenden Sie eine der 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 abfragen, indem Sie die Ansicht pg_stat_statements abfragen, wie im folgenden Beispiel gezeigt:
```
select query, queryid from pg_stat_statements;
```

Benannte Hinweise erstellen

Verwenden Sie die Funktion google_create_named_hints(), um benannte Hinweise zu erstellen. Dadurch wird 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 Name muss in 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 zu verwenden, da AlloyDB den normalisierten Abfragetext automatisch anhand der Abfrage-ID ermittelt.
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. Jede Abweichung, einschließlich der Groß-/Kleinschreibung, kann dazu führen, dass die benannten Hinweise nicht angewendet werden. Informationen zum Erstellen benannter Hinweise für Abfragen mit Literalen und Konstanten, siehe Parameterabhängige 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 werden benannte Hinweise 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 der Ansicht 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 in der primären Instanz erstellt wurden, werden sie automatisch auf die zugehörigen Abfragen in der Lesepoolinstanz angewendet, sofern Sie das Feature 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, indem alle Literal- und Konstantenwerte im Abfragetext durch eine Parameterkennzeichnung wie ? ersetzt werden. Die benannten Hinweise werden dann für diese normalisierte Abfrage verwendet, auch wenn der Wert für die Parameterkennzeichnung unterschiedlich ist.

Wenn Sie beispielsweise die folgende Abfrage ausführen, kann eine andere Abfrage wie SELECT * FROM t WHERE a = 99; standardmäßig die benannten Hinweise my_hint2 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);

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

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

Wenn Sie parameterabhängige benannte Hinweise anwenden, werden auch zwei Abfragen, die sich nur in den entsprechenden Literal- oder Konstantenwerten unterscheiden, 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 Hinweise für die beiden benannten Hinweise verwenden.

Wenn Sie parameterabhängige benannte Hinweise erstellen möchten, legen Sie den Parameter SENSITIVE_TO_PARAM der Funktion google_create_named_hints() auf TRUE fest, 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 parameterabhängiger benannter Hinweise Folgendes:

Parameterabhängige benannte Hinweise unterstützen keine Mischung aus Literal- und Konstantenwerten und Parameterkennzeichnungen im Abfragetext.
Wenn Sie parameterabhängige benannte Hinweise und standardmäßige benannte Hinweise für dieselbe Abfrage erstellen, werden die parameterabhängigen benannten Hinweise gegenüber den standardmäßigen benannten Hinweisen bevorzugt.
Wenn Sie die Abfrage-ID verwenden möchten, um parameterabhängige benannte Hinweise zu erstellen, muss die Abfrage in der aktuellen Sitzung ausgeführt werden. Die Parameterwerte aus der letzten Ausführung (in der aktuellen Sitzung) werden verwendet, um die benannten Hinweise zu erstellen.

Anwendung der benannten Hinweise prüfen

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

Verwenden Sie den EXPLAIN Befehl oder den EXPLAIN (ANALYZE) Befehl.

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 auto_explain Erweiterung.

Benannte Hinweise verwalten

In AlloyDB können Sie benannte Hinweise ansehen, aktivieren und deaktivieren sowie löschen.

Benannte Hinweise ansehen

Verwenden Sie die Funktion google_named_hints_view, um vorhandene benannte Hinweise anzusehen, 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

Verwenden Sie die Funktion google_enable_named_hints(HINTS_NAME), um vorhandene benannte Hinweise zu 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 Hinweise deaktivieren

Verwenden Sie die Funktion google_disable_named_hints(HINTS_NAME), um vorhandene benannte Hinweise zu deaktivieren.

Wenn Sie beispielsweise die benannten Hinweise 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.