Abfrageerläuterung verwenden

Mit „Abfrageerläuterung“ können Sie Abfragen im Datastore-Modus an das Backend senden und detaillierte Leistungsstatistiken zur Ausführung von Backendabfragen erhalten. Sie funktioniert in vielen relationalen Datenbanksystemen wie der Vorgang EXPLAIN ANALYZE.

Sie können Anfragen zum Erläutern von Abfragen mithilfe der Clientbibliotheken im Datastore-Modus senden.

Anhand der Ergebnisse der Abfrageerläuterung können Sie nachvollziehen, wie Ihre Abfragen ausgeführt werden. Sie sehen Ineffizienzen und die Standorte wahrscheinlicher serverseitiger Engpässe.

Abfrageerläuterung:

  • Bietet Statistiken zur Planungsphase, damit Sie Ihre Abfrageindexe anpassen und die Effizienz steigern können.
  • Hier können Sie die Kosten und Leistung pro Abfrage nachvollziehen und schnell verschiedene Abfragemuster durchgehen, um die Nutzung zu optimieren.

Optionen für die Abfrageerläuterung: Standard und analysieren

Abfrageerläuterungen können mit der Option standard oder analyze ausgeführt werden.

Bei der Standardoption wird die Abfrage mit Query Explain geplant, die Ausführungsphase wird jedoch übersprungen. Dadurch werden Informationen zur Planungsphase zurückgegeben. So können Sie prüfen, ob eine Abfrage die erforderlichen Indexe enthält, und nachvollziehen, welche Indexe verwendet werden. So können Sie beispielsweise prüfen, ob für eine bestimmte Abfrage ein zusammengesetzter Index verwendet wird, anstatt viele verschiedene Indexe zu überschneiden.

Mit der Analyseoption erstellt Query Explain beide Pläne und führt die Abfrage aus. Dadurch werden alle zuvor genannten Informationen zum Planer sowie Statistiken zur Ausführungszeit der Abfrage zurückgegeben. Dazu gehören Abrechnungsinformationen sowie Statistiken zur Abfrageausführung auf Systemebene. Mit diesen Tools können Sie verschiedene Abfrage- und Indexkonfigurationen testen, um Kosten und Latenz zu optimieren.

Wie viel kostet die Funktion „Abfrage erklären lassen“?

Wenn eine Abfrage mit der Standardoption erläutert wird, werden keine Index- oder Lesevorgänge ausgeführt. Unabhängig von der Komplexität der Abfrage wird ein Lesevorgang berechnet.

Wenn eine Abfrage mit der Option „Analysieren“ erläutert wird, werden Indexierungs- und Lesevorgänge ausgeführt. Die Abfrage wird Ihnen daher wie gewohnt in Rechnung gestellt. Für die Analyseaktivität fallen keine zusätzlichen Kosten an, nur die üblichen Kosten für die ausgeführte Abfrage.

Abfrage mit der Standardoption ausführen

Sie können eine Clientbibliothek verwenden, um eine Anfrage für die Standardoption zu senden.

Die Ergebnisse der Abfrageerläuterung werden mit Identity and Access Management authentifiziert. Dabei werden dieselben Berechtigungen wie für normale Abfragevorgänge verwendet.

Java

Informationen zum Installieren und Verwenden der Clientbibliothek für den Datastore-Modus finden Sie hier. Weitere Informationen finden Sie in der Referenzdokumentation zur Datastore-Modus-Java API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich beim Datastore-Modus zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 


import com.google.cloud.datastore.Datastore;
import com.google.cloud.datastore.DatastoreOptions;
import com.google.cloud.datastore.Entity;
import com.google.cloud.datastore.Query;
import com.google.cloud.datastore.QueryResults;
import com.google.cloud.datastore.models.ExplainMetrics;
import com.google.cloud.datastore.models.ExplainOptions;
import com.google.cloud.datastore.models.PlanSummary;
import java.util.List;
import java.util.Map;
import java.util.Optional;

public class QueryProfileExplain {
  public static void invoke() throws Exception {
    // Instantiates a client
    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();

    // Build the query
    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").build();

    // Set the explain options to get back *only* the plan summary
    QueryResults<Entity> results = datastore.run(query, ExplainOptions.newBuilder().build());

    // Get the explain metrics
    Optional<ExplainMetrics> explainMetrics = results.getExplainMetrics();
    if (!explainMetrics.isPresent()) {
      throw new Exception("No explain metrics returned");
    }
    PlanSummary planSummary = explainMetrics.get().getPlanSummary();
    List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
    System.out.println("----- Indexes Used -----");
    indexesUsed.forEach(map -> map.forEach((key, val) -> System.out.println(key + ": " + val)));
  }
}

Im Feld indexes_used in der Antwort finden Sie Informationen zu den im Abfrageplan verwendeten Indexen:

"indexes_used": [
        {"query_scope": "Collection Group", "properties": "(__name__ ASC)"},
]

Weitere Informationen zum Bericht finden Sie in der Referenz.

Abfrage mit der Option „Analysieren“ ausführen

Sie können eine Clientbibliothek verwenden, um eine Anfrage für die Standardoption zu senden.

Die Ergebnisse der Abfrageanalyse werden mit Identity and Access Management (IAM) authentifiziert. Dabei werden dieselben Berechtigungen wie für normale Abfragevorgänge verwendet.

Java

Informationen zum Installieren und Verwenden der Clientbibliothek für den Datastore-Modus finden Sie hier. Weitere Informationen finden Sie in der Referenzdokumentation zur Datastore-Modus-Java API.

Richten Sie die Standardanmeldedaten für Anwendungen ein, um sich beim Datastore-Modus zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

import com.google.cloud.datastore.Datastore;
import com.google.cloud.datastore.DatastoreOptions;
import com.google.cloud.datastore.Entity;
import com.google.cloud.datastore.Query;
import com.google.cloud.datastore.QueryResults;
import com.google.cloud.datastore.models.ExecutionStats;
import com.google.cloud.datastore.models.ExplainMetrics;
import com.google.cloud.datastore.models.ExplainOptions;
import com.google.cloud.datastore.models.PlanSummary;
import java.util.List;
import java.util.Map;

public class QueryProfileExplainAnalyze {
  public static void invoke() throws Exception {
    // Instantiates a client
    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();

    // Build the query
    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").build();

    // Set explain options with analzye = true to get back the query stats, plan info, and query
    // results
    QueryResults<Entity> results =
        datastore.run(query, ExplainOptions.newBuilder().setAnalyze(true).build());

    // Get the result set stats
    if (!results.getExplainMetrics().isPresent()) {
      throw new Exception("No explain metrics returned");
    }
    ExplainMetrics explainMetrics = results.getExplainMetrics().get();

    // Get the execution stats
    if (!explainMetrics.getExecutionStats().isPresent()) {
      throw new Exception("No execution stats returned");
    }

    ExecutionStats executionStats = explainMetrics.getExecutionStats().get();
    Map<String, Object> debugStats = executionStats.getDebugStats();
    System.out.println("----- Debug Stats -----");
    debugStats.forEach((key, val) -> System.out.println(key + ": " + val));
    System.out.println("----------");

    long resultsReturned = executionStats.getResultsReturned();
    System.out.println("Results returned: " + resultsReturned);

    // Get the plan summary
    PlanSummary planSummary = explainMetrics.getPlanSummary();
    List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
    System.out.println("----- Indexes Used -----");
    indexesUsed.forEach(map -> map.forEach((key, val) -> System.out.println(key + ": " + val)));

    if (!results.hasNext()) {
      throw new Exception("query yielded no results");
    }

    // Get the query results
    System.out.println("----- Query Results -----");
    while (results.hasNext()) {
      Entity entity = results.next();
      System.out.printf("Entity: %s%n", entity);
    }
  }
}

Im executionStats-Objekt finden Sie Informationen zum Abfrage-Profiling, z. B.:

{
    "resultsReturned": "5",
    "executionDuration": "0.100718s",
    "readOperations": "5",
    "debugStats": {
               "index_entries_scanned": "95000",
               "documents_scanned": "5"
               "billing_details": {
                     "documents_billable": "5",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}

Weitere Informationen zum Bericht finden Sie in der Referenz.

Ergebnisse interpretieren und Anpassungen vornehmen

Im folgenden Beispielszenario werden Filme nach Genre und Produktionsland abgefragt. Außerdem wird gezeigt, wie die für die Abfrage verwendeten Indexe optimiert werden.

Weitere Informationen zum Bericht finden Sie in der Referenz zum Bericht „Erläuterung von Abfragen“.

Angenommen, Sie haben die folgende SQL-Abfrage.

SELECT *
FROM movies
WHERE category = 'Romantic' AND country = 'USA';

Wenn wir die Analyseoption verwenden, zeigt die folgende Berichtsausgabe, dass die Abfrage auf den Einzelfeldindexen (category ASC, __name__ ASC) und (country ASC, __name__ ASC) ausgeführt wird. Es werden 16.500 Indexeinträge gescannt, aber nur 1.200 Dokumente zurückgegeben.

// Output query planning info
"indexes_used": [
    {"query_scope": "Collection Group", "properties": "(category ASC, __name__ ASC)"},
    {"query_scope": "Collection Group", "properties": "(country ASC, __name__ ASC)"},
]

// Output query status
{
    "resultsReturned": "1200",
    "executionDuration": "0.118882s",
    "readOperations": "1200",
    "debugStats": {
               "index_entries_scanned": "16500",
               "documents_scanned": "1200"
               "billing_details": {
                     "documents_billable": "1200",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}

Um die Leistung der Abfrageausführung zu optimieren, können Sie einen vollständig abgedeckten zusammengesetzten Index erstellen (Kategorie ASC, Land ASC, __name__ ASC).

Wenn wir die Abfrage noch einmal im Analysemodus ausführen, sehen wir, dass der neu erstellte Index für diese Abfrage ausgewählt ist. Die Abfrage wird viel schneller und effizienter ausgeführt.

// Output query planning info
    "indexes_used": [
        {"query_scope": "Collection Group", "properties": "(category ASC, country ASC, __name__ ASC)"}
        ]

// Output query stats
{
    "resultsReturned": "1200",
    "executionDuration": "0.026139s",
    "readOperations": "1200",
    "debugStats": {
               "index_entries_scanned": "1200",
               "documents_scanned": "1200"
               "billing_details": {
                     "documents_billable": "1200",
                     "index_entries_billable": "0",
                     "small_ops": "0",
                     "min_query_cost": "0",
               }
    }
}

Nächste Schritte