Zero-copy raw batch cursor API

[SilasMarvin]

Problem Statement

The current MongoDB Rust driver's find() method deserializes each document individually, which creates performance bottlenecks for high-throughput workloads.

This came up while optimizing bulk document processing at Rippling, where we're seeing overhead from per-document deserialization in our benchmarks.

Proposed Solution

Add a find_raw_batches() API that returns server response batches directly as RawDocumentBuf without per-document deserialization.

API Example

use futures::stream::StreamExt;
use mongodb::bson::RawDocument;

// Returns a Stream of RawBatch items
let mut cursor: RawBatchCursor = db.find_raw_batches("coll", doc! {}).await?;

while let Some(batch_result) = cursor.next().await {
    let batch: RawBatch = batch_result?;

    // Zero-copy access to the batch array (firstBatch/nextBatch)
    let docs: &RawArray = batch.doc_slices()?;

    // Iterate over documents in the batch without allocation
    for doc_result in docs.into_iter() {
        // Process raw document - can extract fields, forward bytes, etc.
        // No per-document deserialization overhead
    }
}

Performance Impact

In my benchmarks against the existing find() with raw BSON (which already skips typed deserialization), the raw batch API shows meaningful performance improvements. I've included it in the driver's benchmark suite for comparison.

Implementation Notes

I have a working implementation on a branch that:

• Adds Database::find_raw_batches() method
• Implements RawBatchCursor that yields RawBatch items
• Supports both implicit and explicit sessions
• Includes some tests and benchmarks
• Uses the existing RawDocumentBuf infrastructure; no unsafe code required

The implementation reuses existing cursor machinery and operation execution paths with a new handle_response_owned() hook that takes ownership of the response buffer rather than borrowing it.

Questions for Maintainers

1. Is this feature aligned with the driver's roadmap?
2. Are there API naming or design preferences? (e.g., find_raw_batches vs find_batches_raw)
3. Any concerns about the implementation approach?

I'm happy to refine the implementation based on feedback and would be excited to contribute this upstream if there's interest.

[alexbevi]

Hey @SilasMarvin, thanks for sharing a POC and for the thorough issue report :) We'll have the team review this and share feedback.

[isabelatkinson]

I filed RUST-2300 to track this work and will discuss it in more detail with the team next week.

[SilasMarvin]

Thank you for the positive feedback and for creating RUST-2300 to track this!

I'm happy to update my branch to align with your team's standards for code quality and API design. Please let me know if that is something you are interested in me doing and the next steps after your internal discussion.

[abr-egn]

Thanks again for putting this branch together - it's really helpful to have the code and benchmark so we can see where the current implementation falls short.

Our current perspective is that we'd much rather fold your improvements into the existing Cursor implementation so that iteration using the existing API doesn't bottleneck; failing that, we'd provide a batch-iteration API on Cursor so everything that returns one can benefit rather than it being specific to find.

In a happy coincidence, I was just wrapping something up, so we've shuffled our schedule around so I can spend the next week or so to implement that 🙂

To make sure I understand your needs - if the current zero-copy advance/current methods can be brought up in benchmark to match your RawBatchCursor performance, would that work, or is there something specific about consuming batches?

[SilasMarvin]

Of course @abr-egn Thank you for jumping on it!

Ideally we can get the actual batch directly. To give more context, the ideal flow in our code would look something like:

1. We issue a find command that returns a Stream over raw bytes of documents
2. We parallelize deserialization directly over these bytes -- ideally without any copying

In reality this will look something like a tokio thread streaming batches and shipping each batch directly to some thread pool.

There are two reasons we want to avoid receiving individual items back from the cursor:

1. To parallelize effectively we have to gather it into a batch. This is duplicate work as we started with a batch
2. Streaming individual owned items requires some kind of cloning. If we get the raw batch directly we can operate on slices without cloning

It would be awesome if you can boost the cursor performance to that of the RawBatchCursor. Correct me if I'm wrong, but that indicates there is even higher performance that can be squeezed out of the RawBatchCursor. My thinking being it should always be faster to provide one zero-copy batch of bytes rather than N individual owned buffers.

[univerz]

I would also like something like that - or at least know how many items are already downloaded locally so I can quickly pull them out of the cursor and send them for further processing while more data is being downloaded from the database in parallel.