Skip to content

MongoIterable

interface MongoIterable<Document : Any>

Streaming-capable iterable cursor to read data from the database.

External resources

Functions

asFlow

abstract fun asFlow(): Flow<Document>

Streams the results into a Flow.

The flow is lazy: new elements are streamed in when the consumer requests them.

MongoDB cursors are batched: a batch is queried, processed, then another batch is requested, etc. The batch size can be configured in the operation creating this iterable.

If you intend to query a large number of batches and perform complex operations on them, we recommend using buffer with a low capacity, to reduce latency between two batches.

See also

asSequence

Deprecated (with error)

Kotlin Sequences are not capable of closing a resource after they are done. Using sequences with a MongoIterable will create memory leaks. Instead, use toList, forEach, stream (Java only) or the coroutines driver's asFlow

Replace with

<div class="highlight"><pre><code class="md-code__content"><span markdown>this.toList().asSequence()
</span></code></pre></div>

This method always throws an exception.

Streaming a MongoIterable into a Sequence is not supported, because iterables must be closed, and sequences cannot detect when iteration finishes.

If you want to use a Sequence data structure for convenience, and the volume of data is low, use toList followed by asSequence. All data will be loaded in memory at once.

If streaming is important, either use forEach, asFlow or stream (Java-only).

See also

first

abstract suspend fun first(): Document

Returns the first document found by this query, or throws an exception.

See also

  • firstOrNull: Return null instead of throwing an exception.

Throws

NoSuchElementException

If this query returned no results.

firstOrNull

abstract suspend fun firstOrNull(): Document?

Returns the first document found by this query, or returns null.

See also

  • first: Throw an exception instead of returning null.

forEach

abstract suspend fun forEach(action: suspend (Document) -> Unit)

Executes action for each document returned by this query.

This method streams all returned documents into the action function. The entire response set is not loaded at once into memory.

MongoDB cursors are batched: a batch is queried, processed, then another batch is requested, etc. The batch size can be configured in the operation creating this iterable.

If the operation contains a sort without an index, MongoDB will load all results into memory. The driver will still stream the results.

See also

toList

open suspend fun toList(): List<Document>

Reads the entirety of this iterable into a List.

Since lists are in-memory, this method loads the entirety of the results into memory.

See also

toSequence

Deprecated (with error)

Kotlin Sequences are not capable of closing a resource after they are done. Using sequences with a MongoIterable will create memory leaks. Instead, use toList, forEach, stream (Java only) or the coroutines driver's asFlow

Replace with

<div class="highlight"><pre><code class="md-code__content"><span markdown>this.toList().asSequence()
</span></code></pre></div>

This method always throws an exception.

Streaming a MongoIterable into a Sequence is not supported, because iterables must be closed, and sequences cannot detect when iteration finishes.

If you want to use a Sequence data structure for convenience, and the volume of data is low, use toList followed by asSequence. All data will be loaded in memory at once.

If streaming is important, either use forEach, asFlow or stream (Java-only).

See also

toSet

open suspend fun toSet(): Set<Document>

Reads the entirety of this iterable into a Set.

Since sets are in-memory, this method loads the entirety of the results into memory.

See also