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.

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 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êtes 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 d'explication des requêtes peuvent être effectuées à l'aide de l'option par défaut ou analyser.

Avec l'option par défaut, Query Explain planifie la requête, mais ignore l'étape d'exécution. Les informations sur les étapes du planificateur s'affichent. 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 Query Explain ?

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 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 n'entraîne aucuns frais supplémentaires, mais uniquement les frais habituels pour la requête exécutée.

Utiliser Query Explain avec l'option par défaut

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

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 sur l'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 Query Explain 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 sur l'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 "Explication des requêtes".

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 sont susceptibles de changer à mesure que Cloud 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 Cloud Firestore. Pour en savoir plus, consultez la documentation de référence sur le rapport "Explication des requêtes".

À 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 pouvons voir que l'index nouvellement créé est sélectionné pour cette requête, et qu'elle 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",
               }
    }
}