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

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

Query Explain vous permet d'envoyer des requêtes Firestore au backend et de recevoir en retour des statistiques de performances détaillées sur l'exécution des requêtes dans le backend. Elle fonctionne comme l'opération EXPLAIN [ANALYZE] dans de nombreux systèmes de base de données relationnelle.

Les requêtes d'explication de requête peuvent être envoyées à l'aide des bibliothèques clientes du serveur Firestore.

Les résultats de la fonctionnalité Query Explain vous aident à comprendre comment vos requêtes sont exécutées, en mettant en évidence 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 des requêtes afin que vous puissiez ajuster vos index de requête et améliorer l'efficacité.
• L'option d'analyse vous permet de comprendre les coûts et les performances pour chaque requête, et d'itérer rapidement les différents modèles de requête afin d'optimiser leur utilisation.

Remarque :Query Explain est compatible avec les requêtes interrogées. Les requêtes en streaming ne sont pas encore compatibles.

Comprendre les options Query Explain : "default" et "analyze"

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 ainsi des informations sur les étapes du planificateur. Cela vous permet de vérifier qu'une requête dispose des index nécessaires et de comprendre quels index sont utilisés. Cela vous aidera à vérifier, par exemple, qu'une requête particulière utilise un index composite plutôt que de devoir croiser de nombreux index différents.

Avec l'option d'analyse, Query Explain permet de planifier et d'exécuter la requête. Cela renvoie toutes les informations de planificateur mentionnées précédemment, ainsi que les statistiques de l'environnement d'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 Query Explain ?

Lorsque vous utilisez Query Explain avec l'option par défaut, aucune opération d'index ou de lecture n'est effectuée. Quelle que soit la complexité de la requête, une opération de lecture est facturée.

Lorsque vous utilisez Query Explain avec l'option d'analyse, des opérations d'index et de lecture sont effectuées. La requête vous est donc facturée comme d'habitude. L'activité d'analyse est gratuite. Seuls les frais habituels sont facturés pour l'exécution de la requête.

Utiliser Query Explain 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 d'explication de requête.

Utiliser Query Explain avec l'option d'analyse

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

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.

Remarque :Une exécution de requête est analysée à la fois. Par conséquent, les résultats de durée de requête peuvent varier d'une requête à l'autre. Cet outil peut vous aider à détecter des inefficacités structurelles importantes, mais n'est pas destiné à fournir des statistiques globales 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 les films par genre et pays de production.

Remarque :Query Explain est conçu pour effectuer des analyses ad hoc utiles. Son format de rapport évoluera pour optimiser la facilité de lecture et de compréhension, et non pour l'adapter au traitement par une machine. Certaines métriques sont susceptibles de changer à mesure que Firestore évolue (par exemple, des métriques peuvent être ajoutées, supprimées ou mises à jour) et ne sont pas couvertes par le même règlement d'abandon que les autres API Firestore. Pour en savoir plus, consultez la documentation de référence du rapport Query Explain.

À titre d'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 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 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",
               }
    }
}