Utiliser "Expliquer la requête"

L'onglet "Explication de la requête" vous permet d'envoyer des requêtes en mode Datastore au backend et de recevoir en retour des statistiques détaillées sur les performances de l'exécution des requêtes backend. Il fonctionne comme l'opération EXPLAIN ANALYZE dans de nombreux systèmes de bases de données relationnelles.

Vous pouvez envoyer des requêtes "Explication de la requête" à l'aide des bibliothèques clientes en mode Datastore.

Les résultats de l'onglet "Explication de la requête" vous aident à comprendre comment vos requêtes sont exécutées, en vous montrant les inefficacités et l'emplacement des goulots d'étranglement potentiels côté serveur.

Explication de la requête :

• Fournit des insights sur la phase de planification afin que vous puissiez ajuster vos index de requête et améliorer l'efficacité.
• Vous aide à comprendre vos coûts et vos performances par requête, et vous permet d'itérer rapidement sur différents modèles de requête afin d'optimiser leur utilisation.

Comprendre les options de l'onglet "Explication de la requête" : "default" et "analyze"

Les opérations de l'onglet "Explication de la requête" peuvent être effectuées à l'aide de l'option default ou analyze.

Avec l'option "default", l'onglet "Explication de la requête" planifie la requête, mais ignore l'étape d'exécution. Cela renvoie des informations sur l'étape de planification. Vous pouvez les utiliser pour vérifier qu'une requête dispose des index nécessaires et comprendre quels index sont utilisés. Cela vous aidera, par exemple, à vérifier qu'une requête particulière utilise un index composite plutôt que d'avoir à croiser de nombreux index différents.

Avec l'option "analyze", l'onglet "Explication de la requête" planifie et exécute la requête. Cela renvoie toutes les informations de planification mentionnées précédemment, ainsi que des statistiques provenant de l'environnement d'exécution de la requête. Cela inclut des informations de facturation ainsi que des insights au niveau du système sur l'exécution de la requête. Vous pouvez utiliser cet outil pour tester différentes configurations de requêtes et d'index afin d'optimiser leur coût et leur latence.

Quel est le coût de l'onglet "Explication de la requête" ?

Lorsqu'une requête est expliquée avec l'option "default", aucune opération d'indexation ni de lecture n'est effectuée. Quel que soit le niveau de complexité de la requête, une opération de lecture est facturée.

Lorsqu'une requête est expliquée avec l'option "analyze", des opérations d'indexation et de lecture sont effectuées. Vous êtes donc facturé pour la requête comme d'habitude. L'activité d'analyse n'entraîne aucun frais supplémentaire, mais uniquement les frais habituels pour l'exécution de la requête.

Exécuter une requête avec l'option "default"

Vous pouvez utiliser une bibliothèque cliente pour envoyer une requête avec l'option "default".

Notez que les résultats de l'onglet "Explication de la requête" sont authentifiés avec Identity and Access Management, en utilisant les mêmes autorisations que pour les opérations de requête standards.

Remarque : Une seule exécution de requête est analysée à la fois. Par conséquent, les résultats de l'onglet "Explication de la requête" peuvent varier d'une requête à l'autre. L'outil peut vous aider à identifier les inefficacités structurelles importantes, mais il n'est pas conçu pour fournir des statistiques agrégées sur les performances des requêtes.

Java

Pour savoir comment installer et utiliser la bibliothèque cliente pour le mode Datastore, consultez Bibliothèques clientes en mode Datastore. Pour en savoir plus, consultez la documentation de référence de l'API en mode DatastoreJava.

Pour vous authentifier auprès du mode Datastore, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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)));
  }
}

Consultez le champ indexes_used dans la réponse pour en savoir plus sur les index utilisés dans le plan de requête :

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

Pour en savoir plus sur le rapport, consultez la documentation de référence sur le rapport.

Exécuter une requête avec l'option "analyze"

Vous pouvez utiliser une bibliothèque cliente pour envoyer une requête avec l'option "default".

Notez que les résultats de l'onglet "Analyse de la requête" sont authentifiés avec Identity and Access Management (IAM), en utilisant les mêmes autorisations que pour les opérations de requête standards.

Remarque : Une seule exécution de requête est analysée à la fois. Par conséquent, les résultats de l'onglet "Analyse de la requête" peuvent varier d'une requête à l'autre. L'outil peut vous aider à identifier les inefficacités structurelles importantes, mais il n'est pas conçu pour fournir des statistiques agrégées sur les performances des requêtes.

Java

Pour savoir comment installer et utiliser la bibliothèque cliente pour le mode Datastore, consultez Bibliothèques clientes en mode Datastore. Pour en savoir plus, consultez la documentation de référence de l'API en mode DatastoreJava.

Pour vous authentifier auprès du mode Datastore, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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);
    }
  }
}

Consultez l'objet executionStats pour trouver des informations de profilage de requête telles que :

{
    "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",
               }
    }
}

Pour en savoir plus sur le rapport, consultez la documentation de référence sur le rapport.

Interpréter les résultats et effectuer des ajustements

L'exemple de scénario suivant interroge des films par genre et pays de production, et montre comment optimiser les index utilisés par la requête.

Remarque : L'onglet "Explication de la requête" est conçu pour une analyse ad hoc utile. Le format de son rapport évoluera pour faciliter la lecture et la compréhension, et non pour être adapté au traitement automatique. Certaines métriques renvoyées devraient changer à mesure que le mode Datastore évolue (des métriques peuvent être ajoutées, supprimées ou mises à jour). Elles ne sont pas couvertes par le même règlement relatif aux abandons que les autres API en mode Datastore.

Pour en savoir plus sur le rapport, consultez la documentation de référence sur le rapport "Explication de la requête".

Pour illustrer cela, prenons pour exemple la requête SQL équivalente.

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

Si nous utilisons l'option "analyze", le résultat du rapport suivant indique que la requête s'exécute sur des index à un seul champ (category ASC, __name__ ASC) et (country ASC, __name__ ASC). Elle analyse 16 500 entrées d'index, mais ne renvoie que 1 200 documents.

// 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",
               }
    }
}

Pour optimiser les performances d'exécution de la requête, vous pouvez créer un index composite entièrement couvert (category ASC, country ASC, __name__ ASC).

En exécutant à nouveau la requête en mode "analyze", nous pouvons constater que l'index nouvellement créé est sélectionné pour cette requête, et que la requête s'exécute beaucoup plus rapidement et efficacement.

// 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",
               }
    }
}

Étape suivante

• En savoir plus sur le rapport "Explication de la requête"
• En savoir plus sur l'optimisation des requêtes et des index