MongoClient bulkWrite multi-namespace batching and result cursors
Parent: MongoDB Driver Internals · Published reference · snapshot 2026-10-29
↓ Facts as markdownall context files
Source-anchored research for MongoClient bulkWrite multi-namespace batching and result cursors. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Definitions
- Each ops entry refers to a zero-based nsInfo index. Drivers deduplicate namespaces and include only namespaces referenced by that command batch. (medium confidence) [source]
How it works
- Result cursors prevent a single response array from exceeding BSON size limits. Drivers must consume them even for summary results because they carry write errors. (low confidence) [source]
Problems, failure modes and limitations
- JAVA-6226 reports that a top-level failure while exhausting a result cursor discards documents already observed from that cursor. DRIVERS-3542 requests specification clarification, so specification prose alone does not establish that every driver preserves partial cursor results. (medium confidence) (verified as of 2026-07-22) [source]
- GODRIVER-4169 reports distinct Go client-bulk-write failures: top-level command errors can disappear when write errors exist; successful partial results can disappear when only a later command error remains; cursor-close errors can be ignored. The ticket was unresolved and marked Needs Review in its October 22, 2026 update; this is a reported defect, not an independently reproduced incident. (low confidence) (verified as of 2026-10-22) [source]
- The server idx identifies an operation within the command batch. The Node.js results merger adds currentBatchOffset to write-error and verbose-result keys and advances that offset by the batch operation count. (high confidence) (verified as of 2026-10-27) [source]
- The bulkWrite command runs against admin even when target namespaces name other databases. SAP’s adapter guide documents an Unauthorized error when Run Command targets another database and prescribes setting the adapter database to admin. (high confidence) [source]
Facts and statements
- MongoDB introduced multi-collection insert/update/delete batching in 8.0; Percona Server for MongoDB 8.0.4-1 also documents this capability. (high confidence) [source]
- Unencrypted bulkWrite uses OP_MSG document sequences for ops and nsInfo, runs on admin, and deduplicates namespaces. (low confidence) [source]
- Drivers split commands at hello-advertised size/count limits, include only each batch's namespaces, reserve 1000 overhead bytes for unencrypted messages, and merge batch results. (low confidence) [source]
- Driver verboseResults defaults false and inversely controls errorsOnly. The raw server command instead defaults errorsOnly false, so raw-command defaults return more detail. (high confidence) [source]
- Drivers must drain result cursors even for summary results, using getMore in the same session; load-balanced cursors retain the original connection. (low confidence) [source]
- Cursor idx identifies the batch operation; public result maps use original input indexes. Drivers may need to retain their write models to reconstruct result types and confirm insert success. (low confidence) [source]
- Ordinary top-level failures halt even unordered batches; drivers preserve observed results/errors in BulkWriteException and attempt killCursors for unfinished cursors. (medium confidence) [source]
- SERVER-90050 documents a historical mongos child-batch defect: copying the entire nsInfo array could exceed BSON limits or waste batch space. The proposed remedy rebuilt child namespace lists and remapped operation indexes. The ticket lists fixes in 8.0.0-rc6 and 8.1.0-rc0; it does not establish a current production defect. (low confidence) (verified as of 2026-09-21) [source]
- Skynet's independent Lua MongoDB client builds ops with zero-based indexes into a deduplicated nsInfo array, then submits bulkWrite through its admin-command helper. Its source explicitly omits let, cursor, and writeConcern parameters; this implementation demonstrates namespace encoding but does not establish official-driver result-cursor compliance. (low confidence) (verified as of 2026-10-27) [source]
- MongoClient.bulkWrite targets mixed namespaces through the MongoDB 8.0 bulkWrite command; collection-level bulkWrite remains a distinct API. (high confidence) [source]
- Without automatic encryption, drivers encode ops and nsInfo as OP_MSG type-1 document sequences; with automatic encryption, both become command-document arrays. (low confidence) [source]
- One API call may require several commands. Drivers split at hello-advertised maxWriteBatchSize and applicable BSON/message size limits, then merge results. (low confidence) [source]
- Unencrypted batching reserves 1000 bytes of message overhead; the command-specific document plus ops and nsInfo must fit maxMessageSizeBytes minus that allowance. (low confidence) [source]
- A nonzero result cursor requires getMore using the original session; load-balanced deployments require the connection that created the cursor. (low confidence) [source]
- Cursor result documents omit operation type. The Node.js merger uses cursor.operations[idx] to reconstruct insert, update, or delete results and obtains insertedId from the corresponding insert document. (high confidence) (verified as of 2026-10-27) [source]
- Except for eligible client-backpressure errors that SHOULD retry getMore, top-level failures halt ordered and unordered bulks. For an unexhausted cursor, drivers attempt killCursors and inspect its response. (low confidence) (verified as of 2026-10-29) [source]
- Percona’s 8.0.4-1 release identifies its server as supporting MongoDB Community protocols and drivers and includes the multi-collection bulkWrite command among its inherited features. (low confidence) (verified as of 2024-12-17) [source]
Children
- Per-batch namespace-index remapping (frontier)
- Bulk-write cursor partial-result preservation (frontier)
- OP_MSG document sequences and namespace remapping (frontier)
- Client bulk-write result index reconstruction (frontier)
- Bulk-write result cursor lifecycle (frontier)
Frontier under this node: Bulk-write cursor partial-result preservation, Bulk-write result cursor lifecycle, Client bulk-write result index reconstruction, OP_MSG document sequences and namespace remapping, Per-batch namespace-index remapping