[DOCS-14045] Investigate changes in SERVER-48625: explain() output structure in 5.0 Created: 10/Dec/20  Updated: 13/Nov/23  Due: 14/May/21  Resolved: 10/May/21

Status: Closed
Project: Documentation
Component/s: manual, Server
Affects Version/s: None
Fix Version/s: 4.9.0, Server_Docs_20231030, Server_Docs_20231106, Server_Docs_20231105, Server_Docs_20231113

Type: Task Priority: Major - P3
Reporter: Backlog - Core Eng Program Management Team Assignee: Joseph Dougherty
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Documented
documents SERVER-48625 Explain (and logs) should indicate wh... Closed
Participants:
Days since reply: 2 years, 39 weeks, 2 days ago
Epic Link: DOCSP-9747
Story Points: 2

 Description   

Description

Downstream Change Summary

This ticket adds fields to explain for the following three query parameters: internalQueryMaxScansToExplode (maxScansToExplodeReached), internalQueryEnumerationMaxOrSolutions (maxIndexedOrSolutionsReached), and internalQueryMaxIntersectPerAnd (maxIndexedAndSolutionsReached). When the planner hits the limits set with these knobs, the value in explain will be set to "true" and a message will be logged at log level 1. If the user does not change the values of these knobs, they will still be set if the planner hits the default limits.

Description of Linked Ticket

There are a handful of parameters that influence the plan generation process.  Two examples would be internalQueryEnumerationMaxOrSolutions and internalQueryMaxScansToExplode.  When encountered, these modify the set of plans that are available for selection and can have an important impact on the overall efficiency of the query (eg SERVER-36393).

In some situations, it is relatively easy to determine that such a threshold was encountered during planning with a high degree of confidence.  For example if the query shape is a (singled) contained $or and there are precisely ten plans that contain a "OR" stage then it is very likely that the deployment is using the default value of 10 for the internalQueryEnumerationMaxOrSolutions parameter and that the threshold was encountered during the planning process.  However it very quickly becomes difficult or impossible to definitively determine that these various thresholds were reached in an arbitrary situation.  

We should report when the planner encounters these situations in explain output.  It is also worth considering adding this to the log output as well (verbose or otherwise).

Scope of changes

  1. https://docs.mongodb.com/manual/reference/explain-results/index.html
    1. Be sure to document output for both sharded and unsharded collections.
  2. https://docs.mongodb.com/manual/reference/method/db.collection.explain/index.html
  3. https://docs.mongodb.com/manual/reference/method/cursor.explain/index.html
  4. https://docs.mongodb.com/manual/reference/operator/meta/explain/index.html
  5. https://docs.mongodb.com/manual/reference/command/explain/index.html

Impact to Other Docs

MVP (Work and Date)

Resources (Scope or Design Docs, Invision, etc.)



 Comments   
Comment by Githook User [ 10/May/21 ]

Author:

{'name': 'Joseph Dougherty', 'email': 'joseph.dougherty@mongodb.com', 'username': 'jmd-mongo'}

Message: DOCS-14045 documents new explain fields
Branch: v5.0
https://github.com/mongodb/docs/commit/1fdc1eb15c68066c5e22c09e3b78d1b88aab2520

Comment by Ted Tuckman [ 22/Apr/21 ]

1. They should be able to, but I don't think we expect them to actually use that unless they really know what they're doing. Generally speaking we mark things internal to note that users shouldn't depend on the behavior. I'd direct you to christopher.harris for the original purpose of the ticket.

2. Do you have links for what you're talking about for explain 5.0? Its likely that should be documented separately, as I doubt we need to do any documentation on internal parameters.

Generated at Thu Feb 08 08:09:22 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.