Cette page a été traduite par l'API Cloud Translation.

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

L'explication des requêtes vous permet d'envoyer des requêtes Firestore en mode natif au backend et de recevoir en retour des statistiques détaillées sur les performances de l'exécution des requêtes dans le backend. Elle fonctionne comme l'opération EXPLAIN [ANALYZE] dans de nombreux systèmes de bases de données relationnelles.

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

Les résultats de l'explication de requête vous aident à comprendre comment vos requêtes sont exécutées. Ils vous indiquent les inefficacités et l'emplacement des probables 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 "Analyser" vous aide à comprendre vos coûts et vos performances pour chaque requête. Elle vous permet également de parcourir rapidement différents modèles de requêtes afin d'optimiser leur utilisation.

Comprendre les options "Expliquer la requête" : "Par défaut" et "Analyser"

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

Avec l'option par défaut, Query Explain planifie la requête, mais ignore l'étape d'exécution. Cette opération renvoie des informations sur l'étape de planification. Vous pouvez l'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 à effectuer une intersection sur plusieurs index différents.

Avec l'option "Analyser", Query Explain planifie et exécute la requête. Cette commande renvoie toutes les informations sur le planificateur mentionnées précédemment, ainsi que des statistiques sur le temps d'exécution de la requête. Cela inclut 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 cet outil 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 "Expliquer la requête" avec l'option par défaut, aucune opération d'index ni 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'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 aucun frais supplémentaire. Seuls les frais habituels s'appliquent à la requête exécutée.

Utiliser "Expliquer 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, en utilisant les mêmes autorisations que pour les opérations de requête 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 "Expliquer la requête".

Utiliser "Expliquer la requête" avec l'option "Analyser"

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

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 "Expliquer la requête".

Interpréter les résultats et effectuer des ajustements

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

Pour illustrer cela, prenons pour exemple 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).

Si nous exécutons à nouveau la requête avec l'option "analyze", nous pouvons voir 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", "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",
               }
    }
}