O Query Explain permite enviar consultas no modo Datastore
para o back-end e receber estatísticas detalhadas de desempenho sobre a execução da consulta de
back-end. Ela funciona como a operação EXPLAIN ANALYZE
em muitos
sistemas de banco de dados relacional.
É possível enviar solicitações do Query Explain usando as bibliotecas de cliente do modo Datastore.
Os resultados do Query Explain ajudam a entender como suas consultas são executadas, mostrando ineficiências e a localização de prováveis gargalos do lado do servidor.
Explicação da consulta:
- Fornece informações sobre a fase de planejamento para que você possa ajustar seus índices de consulta e aumentar a eficiência.
- Ajuda a entender o custo e o desempenho por consulta e permite iterar rapidamente diferentes padrões de consulta para otimizar o uso deles.
Entender as opções de Query Explain: default e analyze
É possível executar as operações do Query Explain usando a opção default ou a opção analyze.
Com a opção padrão, a Query Explain planeja a consulta, mas ignora o estágio de execução. Isso retornará informações do estágio do planejador. É possível usar isso para verificar se uma consulta tem os índices necessários e entender quais índices são usados. Isso ajudará você a verificar, por exemplo, se uma consulta específica está usando um índice composto em vez de precisar cruzar com muitos índices diferentes.
Com a opção de análise, a consulta explica os dois planos e executa a consulta. Isso retorna todas as informações do planejador mencionadas anteriormente, além de estatísticas do ambiente de execução da consulta. Isso inclui informações de faturamento e insights no nível do sistema sobre a execução da consulta. É possível usar essas ferramentas para testar várias configurações de consulta e índice para otimizar o custo e a latência.
Qual é o custo da Query Explain?
Quando uma consulta é explicada com a opção padrão, nenhuma operação de índice ou leitura é realizada. Independentemente da complexidade da consulta, uma operação de leitura é cobrada.
Quando uma consulta é explicada com a opção de análise, as operações de índice e leitura são executadas, portanto, a consulta é cobrada como de costume. Não há cobrança extra para a atividade de análise, apenas a cobrança normal para a consulta que está sendo executada.
Executar uma consulta com a opção padrão
Você pode usar uma biblioteca de cliente para enviar uma solicitação de opção padrão.
Observe que os resultados da explicação da consulta são autenticados com o Identity and Access Management, usando as mesmas permissões para operações de consulta normais.
Java
Para saber como instalar e usar a biblioteca de cliente para o modo Datastore, consulte Bibliotecas de cliente do modo Datastore. Para mais informações, consulte a documentação de referência da API Java do modo Datastore.
Para autenticar no modo Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Veja o campo indexes_used
na resposta para saber mais sobre os índices
usados no plano de consulta:
"indexes_used": [ {"query_scope": "Collection Group", "properties": "(__name__ ASC)"}, ]
Para mais informações, consulte a referência de relatórios.
Executar uma consulta com a opção de análise
Você pode usar uma biblioteca de cliente para enviar uma solicitação de opção padrão.
Observe que os resultados da análise da consulta são autenticados com o Identity and Access Management (IAM), usando as mesmas permissões para operações de consulta normais.
Java
Para saber como instalar e usar a biblioteca de cliente para o modo Datastore, consulte Bibliotecas de cliente do modo Datastore. Para mais informações, consulte a documentação de referência da API Java do modo Datastore.
Para autenticar no modo Datastore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Consulte o objeto executionStats
para encontrar informações de criação de perfil de consulta, como:
{ "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 mais informações, consulte a referência de relatórios.
Interpretar resultados e fazer ajustes
No cenário de exemplo a seguir, consultamos filmes por gênero e país de produção e demonstra como otimizar os índices usados pela consulta.
Para mais informações sobre o relatório, consulte a referência do relatório do Query Explain.
Para fins de ilustração, suponha o equivalente a esta consulta SQL.
SELECT * FROM movies WHERE category = 'Romantic' AND country = 'USA';
Se usarmos a opção de análise, a saída do relatório a seguir vai mostrar
a consulta executada nos índices de campo único (category ASC, __name__ ASC)
e
(country ASC, __name__ ASC)
. Ela verifica 16.500 entradas de índice, mas retorna
apenas 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 otimizar o desempenho da execução da consulta, crie um índice composto totalmente coberto (categoria ASC, país ASC, __name__ ASC).
Ao executar a consulta no modo de análise novamente, podemos ver que o índice recém-criado é selecionado para essa consulta e que a consulta é executada com muito mais rapidez e eficiência.
// 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", } } }
A seguir
- Saiba mais sobre o relatório de explicação de consulta
- Saiba mais sobre como otimizar consultas e índices