Comprendre les performances des requêtes à l'aide de l'explication des requêtes

L'explication des requêtes vous permet d'envoyer des requêtes Cloud Firestore au backend et de recevoir en retour des statistiques de performances détaillées sur 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 d'explication de requête à l'aide des bibliothèques clientes du serveur Firestore.

Les résultats de l'explication des requêtes vous aident à comprendre comment vos requêtes sont exécutées. Ils vous indiquent les inefficacités et l'emplacement des goulots d'étranglement côté serveur.

Explication de la requête :

• Fournit des insights sur la phase de planification des requêtes afin que vous puissiez ajuster vos index de requête et améliorer l'efficacité.
• L'option d'analyse 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êtes afin d'optimiser leur utilisation.

Remarque : L'explication des requêtes est compatible avec les requêtes interrogées. Les requêtes de streaming ne sont pas encore acceptées.

Comprendre les options d'explication des requêtes : par défaut et analyse

Les opérations Query Explain peuvent être effectuées à l'aide de l'option default ou de l'option analyze.

Avec l'option par défaut, Query Explain planifie la requête, mais ignore l'étape d'exécution. Vous obtiendrez alors des informations sur l'étape de planification. Vous pouvez l'utiliser pour vérifier qu'une requête dispose des index nécessaires et identifier les index utilisés. Cela vous aidera à vérifier, par exemple, qu'une requête particulière utilise un indice composite plutôt que d'avoir à s'intersecter sur de nombreux indices différents.

Avec l'option d'analyse, Query Explain génère les deux plans et exécute la requête. Cette commande renvoie toutes les informations du planificateur mentionnées précédemment, ainsi que les statistiques de l'environnement d'exécution de l'exécution de la requête. Cela inclura les informations de facturation de la requête, ainsi que des insights au niveau du système sur l'exécution de la requête. Vous pouvez utiliser ces outils pour tester différentes configurations de requêtes et d'index afin d'optimiser leur coût et leur latence.

Combien coûte l'explication des requêtes ?

Lorsque vous utilisez l'option par défaut de l'explication de requête, aucune opération d'indexation ni de lecture n'est effectuée. Une opération de lecture est facturée, quelle que soit la complexité de la requête.

Lorsque vous utilisez l'explication de requête avec l'option d'analyse, des opérations d'indexation et de lecture sont effectuées. La requête vous est donc facturée comme d'habitude. L'activité d'analyse n'entraîne aucuns frais supplémentaires, mais uniquement les frais habituels pour la requête exécutée.

Utiliser l'explication de la requête avec l'option par défaut

Vous pouvez utiliser les bibliothèques clientes pour envoyer une demande d'option par défaut.

Notez que les requêtes sont authentifiées avec IAM et utilisent les mêmes autorisations pour les opérations de requête standards. Les autres techniques d'authentification, telles que Firebase Authentication, sont ignorées. Pour en savoir plus, consultez le guide IAM pour les bibliothèques clientes de serveur.

Java (administrateur)

Query q = db.collection("col").whereGreaterThan("a", 1);
ExplainOptions options = ExplainOptions.builder().build();

ExplainResults<QuerySnapshot> explainResults = q.explain(options).get();
ExplainMetrics metrics = explainResults.getMetrics();
PlanSummary planSummary = metrics.getPlanSummary();

    

Nœud (administrateur)

const q = db.collection('col').where('country', '=', 'USA');
const options = { analyze : 'false' };

const explainResults = await q.explain(options);

const metrics = explainResults.metrics;
const plan = metrics.planSummary;

    

Le format exact de la réponse dépend de l'environnement d'exécution. Les résultats renvoyés peuvent être convertis au format JSON. Exemple :

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

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

Utiliser l'explication de requête avec l'option d'analyse

Vous pouvez utiliser les bibliothèques clientes pour envoyer une requête d'option d'analyse.

Notez que les requêtes sont authentifiées avec IAM, en utilisant les mêmes autorisations que pour les opérations de requêtes standards. Les autres techniques d'authentification, comme Firebase Authentication, sont ignorées. Pour en savoir plus, consultez le guide IAM pour les bibliothèques clientes de serveur.

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

Java (administrateur)

Query q = db.collection("col").whereGreaterThan("a", 1);

ExplainOptions options = ExplainOptions.builder().setAnalyze(true).build();

ExplainResults<QuerySnapshot> explainResults = q.explain(options).get();

ExplainMetrics metrics = explainResults.getMetrics();
PlanSummary planSummary = metrics.getPlanSummary();
List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
ExecutionStats stats = metrics.getExecutionStats();

    

Nœud (administrateur)

const q = db.collection('col').where('country', '=', 'USA');

const options = { analyze : 'true' };

const explainResults = await q.explain(options);

const metrics = explainResults.metrics;
const plan = metrics.planSummary;
const indexesUsed = plan.indexesUsed;
const stats = metrics.executionStats;

    

L'exemple suivant montre l'objet stats renvoyé en plus de planInfo. Le format exact de la réponse dépend de l'environnement d'exécution. L'exemple de réponse est au format JSON.

{
    "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, consultez la documentation de référence sur le rapport d'explication de requête.

Interpréter les résultats et procéder à des ajustements

Examinons un exemple de scénario dans lequel nous interrogeons des films par genre et par pays de production.

Remarque : L'explication des requêtes est conçue pour une analyse ponctuelle utile. Son format de rapport évoluera pour maximiser la facilité de lecture et de compréhension, et non l'adaptabilité au traitement par machine. Certaines métriques devraient changer à mesure que Cloud Firestore évolue (c'est-à-dire que des métriques peuvent être ajoutées, supprimées ou mises à jour) et ne sont pas couvertes par la même règle de retrait que les autres API Cloud Firestore. Pour en savoir plus, consultez la documentation de référence sur le rapport "Explication des requêtes".

Pour illustration, supposons l'équivalent de cette requête SQL.

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

Si nous utilisons l'option d'analyse, les métriques renvoyées indiquent que la requête s'exécute sur deux index à champ unique, (category ASC, __name__ ASC) et (country ASC, __name__ ASC). Il analyse 16 500 entrées d'index, mais ne renvoie que 1 200 documents.

// Output query planning info
{
    "indexes_used": [
        {"query_scope": "Collection", "properties": "(category ASC, __name__ ASC)"},
        {"query_scope": "Collection", "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 de l'exécution de la requête, vous pouvez créer un (category ASC, country ASC, __name__ ASC) d'index composite entièrement couvert.

En exécutant à nouveau la requête avec l'option d'analyse, nous constatons que l'index nouvellement créé est sélectionné pour cette requête, et que celle-ci s'exécute beaucoup plus rapidement et plus efficacement.

// Output query planning info
{
    "indexes_used": [
        {"query_scope": "Collection", "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",
               }
    }
}