[DOCS-12249] Docs for SERVER-38063: executionStats or allPlansExecution level explain of an aggregate with a $out does writes Created: 07/Dec/18  Updated: 13/Nov/23  Resolved: 26/Feb/19

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

Type: Task Priority: Major - P3
Reporter: Kay Kim (Inactive) Assignee: Kay Kim (Inactive)
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Documented
documents SERVER-38063 executionStats or allPlansExecution l... Closed
Participants:
Days since reply: 4 years, 50 weeks, 1 day ago
Epic Link: DOCS: 4.2 Server/Tools

 Description   

Description

Description:

We should document that explain of an $out pipeline with "executionStats" or "allPlansExecution" is disallowed in 4.2. This was not enforced in 3.6 or 4.0, the two existing stable versions that support execution-level explain of aggregate (see SERVER-19758).

If users want explain information from an $out pipeline, they have two options:
1) Use the 'queryPlanner' explain verbosity. This will not report execution stats.
2) Run at 'executionStats' or 'allPlansExecution' verbosity, but omit the $out stage from the end of the pipeline. This will display execution stats for the pipeline that feeds the $out stage. Further work is required for $out to supply execution stats itself, without actually performing any writes.

Engineering Ticket Description:

We allow explaining write operations such as the update and delete commands. However, these operations are never supposed to perform writes. An explain of an $out aggregation stage should behave similarly. However, an "executionStats" or "allPlansExecution" verbosity explain of an $out will actually persist the results to the target collection:

> db.inputColl.drop()
false
> db.inputColl.insert({_id: 1})
WriteResult({ "nInserted" : 1 })
> db.inputColl.explain("executionStats").aggregate([{$out: "outputColl"}])
{
	"stages" : [
		{
			"$cursor" : {
				"query" : {
 
				},
				"queryPlanner" : {
					"plannerVersion" : 1,
					"namespace" : "test.inputColl",
					"indexFilterSet" : false,
					"parsedQuery" : {
 
					},
					"queryHash" : "8B3D4AB8",
					"planCacheKey" : "8B3D4AB8",
					"winningPlan" : {
						"stage" : "COLLSCAN",
						"direction" : "forward"
					},
					"rejectedPlans" : [ ]
				},
				"executionStats" : {
					"executionSuccess" : true,
					"nReturned" : 1,
					"executionTimeMillis" : 59,
					"totalKeysExamined" : 0,
					"totalDocsExamined" : 1,
					"executionStages" : {
						"stage" : "COLLSCAN",
						"nReturned" : 1,
						"executionTimeMillisEstimate" : 0,
						"works" : 3,
						"advanced" : 1,
						"needTime" : 1,
						"needYield" : 0,
						"saveState" : 2,
						"restoreState" : 2,
						"isEOF" : 1,
						"direction" : "forward",
						"docsExamined" : 1
					}
				}
			}
		},
		{
			"$out" : {
				"to" : "outputColl",
				"db" : "test",
				"mode" : "replaceCollection",
				"uniqueKey" : {
					"_id" : 1
				}
			}
		}
	],
	"ok" : 1
}
> db.outputColl.find()
{ "_id" : 1 }

This behavior was most likely introduced by the fixes to executionStats agg explain under SERVER-29421.

Instead, we should probably raise an error if a user attempts to perform this operation with an error message such as "$out cannot be explain with 'executionStats' level verbosity or higher". Users who wish to explain an $out operation with execution stats can simply drop the $out stage from the tail of their pipeline.

Scope of changes

includes:

  • the 4.2 compatibility notes, as it is a minor breaking change.
  • source/reference/command/explain.txt
  • source/reference/method/cursor.explain.txt
  • source/reference/method/db.collection.aggregate.txt
  • source/reference/method/db.collection.explain.txt

Impact to Other Docs

MVP (Work and Date)

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



 Comments   
Comment by Githook User [ 26/Feb/19 ]

Author:

{'name': 'Kay Kim', 'username': 'kay-kim', 'email': 'kay.kim@10gen.com'}

Message: DOCS-12249: 4.2 out compatibility reorg
Branch: master
https://github.com/mongodb/docs/commit/8401933621a70b01889f25234a242e08e5049ac1

Comment by Githook User [ 26/Feb/19 ]

Author:

{'name': 'Kay Kim', 'email': 'kay.kim@10gen.com', 'username': 'kay-kim'}

Message: DOCS-12249: 4.2 explain modes and $out agg stage
Branch: master
https://github.com/mongodb/docs/commit/c2ebd7bfc164611e8b76024f0f6cc8dfa2fde7fe

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