Usa la función Query Explain

Query Explain te permite enviar consultas de en modo Datastore al backend y recibir estadísticas de rendimiento detalladas sobre la ejecución de consultas de backend. Funciona como la operación EXPLAIN ANALYZE en muchos sistemas de base de datos relacional.

Puedes enviar solicitudes de Query Explain a través de las bibliotecas cliente en modo Datastore.

Los resultados de Query Explain te ayudan a comprender cómo se ejecutan tus consultas, lo que te muestra las ineficiencias y la ubicación de los posibles cuellos de botella del servidor.

Query Explain ayuda a lo siguiente:

• Proporciona estadísticas sobre la fase de planificación para que puedas ajustar tus índices de consultas y aumentar la eficiencia.
• Te ayuda a comprender tus costos y rendimiento por consulta y te permite iterar rápidamente por medio de patrones de consulta para optimizar su uso.

Comprende las opciones de Query Explain: default y analyze

Las operaciones de Query Explain se pueden realizar con la opción default o analyze.

Con la opción default, Query Explain planifica la consulta, pero omite la etapa de ejecución. Esto devolverá la información de la etapa del planificador. Puedes usar esta opción para verificar que una consulta tenga los índices necesarios y comprenda qué índices se usan. Esto te ayudará a verificar, por ejemplo, que una consulta específica use un índice compuesto en vez de intersectar varios índices distintos.

Con la opción analyze, Query Explain planifica y ejecuta la consulta. Esto devuelve toda la información del planificador mencionada anteriormente junto con estadísticas del tiempo de ejecución de las consultas. Esto incluirá los datos de facturación junto con información a nivel del sistema de la ejecución de la consulta. Puedes usar estas herramientas para probar varias consultas y opciones de configuración de índices para optimizar el costo y la latencia.

¿Cuánto cuesta Query Explain?

Cuando se explica una consulta con la opción default, no se realizan operaciones de indexación ni de lectura. Sin importar la complejidad de la consulta, se cobra una operación de lectura.

Cuando se explica una consulta con la opción analyze, se realizan las operaciones de índice y lectura, por lo que se te cobra por la consulta como de costumbre. No hay cobros adicionales por la actividad de análisis, solo se cobra el cargo habitual por la consulta ejecutada.

Ejecuta una consulta con la opción default

Puedes usar una biblioteca cliente para enviar una solicitud con la opción default.

Ten en cuenta que los resultados de Query Explain se autentican con Identity and Access Management, a través de los mismos permisos para operaciones de consulta habituales.

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

Consulta el campo indexes_used en la respuesta para obtener información sobre los índices que se usan en el plan de consulta:

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

Para obtener más información sobre el informe, consulta la referencia del informe.

Ejecuta una consulta con la opción analyze

Puedes usar una biblioteca cliente para enviar una solicitud con la opción default.

Ten en cuenta que los resultados de Query Explain se autentican con Identity and Access Management (IAM), a través de los mismos permisos para operaciones de consulta habituales.

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

Consulta el objeto executionStats para encontrar información de generación de perfiles de consultas, como la siguiente:

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

Para obtener más información sobre el informe, consulta la referencia del informe.

Interpreta los resultados y haz ajustes

En el siguiente ejemplo, se consultan películas por género y país de producción, y se muestra cómo optimizar los índices que usa la consulta.

Para obtener más información sobre el informe, consulta la referencia del informe de Query Explain.

A modo de ejemplo, supongamos el equivalente de esta consulta en SQL.

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

Si usamos la opción analyze, el siguiente resultado del informe muestra que la consulta se ejecuta en los índices de campo único (category ASC, __name__ ASC) y (country ASC, __name__ ASC). Analiza 16,500 entradas de índice, pero devuelve solo 1,200 documentos.

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

Para optimizar el rendimiento de la ejecución de la consulta, puedes crear un índice compuesto completamente cubierto (category ASC, country ASC, __name__ ASC).

Si vuelves a ejecutar la consulta en modo analyze, podemos ver que para esta consulta se selecciona un índice recién creado y la consulta se ejecuta mucho más rápido y de manera más eficiente.

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

¿Qué sigue?

• Más información sobre el informe de Query Explain
• Más información sobre la optimización de consultas e índices