MongoAggregationPipeline¶

interface MongoAggregationPipeline<Document : Any> : AggregationPipeline<Document>

A multi-stage aggregation pipeline that transforms documents from a MongoDB collection.

Pipelines are immutable. Each stage method returns a new pipeline with the stage appended.

To obtain a pipeline, use MongoCollection.aggregate.

Example¶

class User(
    val name: String,
    val age: Int,
)

users.aggregate()
    .match { User::age gt 18 }
    .sort { ascending(User::name) }
    .toList()

External resources¶

Official documentation

Properties¶

`context`¶

@LowLevelApi
abstract val context: BsonContext

Functions¶

asFlow¶

inline fun <Document : Any> MongoAggregationPipeline<Document>.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

forEach: Execute an action for each result.
toList: Store all results in a List.
toSet: Store all results in a Set.

asIterable¶

@LowLevelApi
abstract fun asIterable(type: KType): MongoIterable<Document>

Access the data of this pipeline as a MongoIterable.

The methods of MongoIterable are available directly on this type as extension methods, there is no need to convert to a MongoIterable yourself.

If type doesn't match Document, the behavior is unspecified.

countTo¶

abstract override fun <Out : Any> countTo(field: Field<Out, Number>): MongoAggregationPipeline<Out>

abstract override fun <Out : Any> countTo(field: KProperty1<Out, Number>): MongoAggregationPipeline<Out>

`embedInLookup`¶

@LowLevelApi
abstract fun embedInLookup(writer: BsonFieldWriter)

`embedInUnionWith`¶

@LowLevelApi
abstract fun embedInUnionWith(writer: BsonFieldWriter)

first¶

inline suspend fun <Document : Any> MongoAggregationPipeline<Document>.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¶

inline suspend fun <Document : Any> MongoAggregationPipeline<Document>.firstOrNull(): Document?

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

See also

first: Throw an exception instead of returning null.

forEach¶

inline suspend fun <Document : Any> MongoAggregationPipeline<Document>.forEach(noinline 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: Store all results in a List.
toSet: Store all results in a Set.
asFlow: Stream all results in a Flow.

group¶

abstract override fun <Out : Any> group(block: AccumulationOperators<Document, Out>.() -> Unit): MongoAggregationPipeline<Out>

limit¶

abstract override fun limit(amount: Long): MongoAggregationPipeline<Document>

abstract override fun limit(amount: Int): MongoAggregationPipeline<Document>

`lookup`¶

open fun <ForeignDocument : Any> lookup(block: LookupStageOperators<Document, ForeignDocument>.() -> Unit): Pipeline<Document>

match¶

abstract override fun match(filter: FilterQuery<Document>.() -> Unit): MongoAggregationPipeline<Document>

`matchExpr`¶

open fun matchExpr(filter: AggregationOperators.() -> Value<Document, Boolean>): Pipeline<Document>

project¶

abstract override fun project(block: ProjectStageOperators<Document>.() -> Unit): MongoAggregationPipeline<Document>

`reinterpret`¶

@DangerousMongoApi
@LowLevelApi
abstract fun <New : Any> reinterpret(): Pipeline<New>

sample¶

abstract override fun sample(size: Int): MongoAggregationPipeline<Document>

set¶

abstract override fun set(block: SetStageOperators<Document>.() -> Unit): MongoAggregationPipeline<Document>

skip¶

abstract override fun skip(amount: Long): MongoAggregationPipeline<Document>

abstract override fun skip(amount: Int): MongoAggregationPipeline<Document>

sort¶

abstract override fun sort(block: SortOptionDsl<Document>.() -> Unit): MongoAggregationPipeline<Document>

toList¶

inline suspend fun <Document : Any> MongoAggregationPipeline<Document>.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

forEach: Execute an action for each result.
toSet: Store all results in a Set.
asFlow: Stream all results in a Flow.

toSet¶

inline suspend fun <Document : Any> MongoAggregationPipeline<Document>.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

forEach: Execute an action for each result.
toList: Store all results in a List.
asFlow: Stream all results in a Flow.

`toString`¶

abstract override fun toString(): String

unionWith¶

abstract override fun unionWith(other: HasUnionWithCompatibility<Document>): MongoAggregationPipeline<Document>

unset¶

abstract override fun unset(block: UnsetStageOperators<Document>.() -> Unit): MongoAggregationPipeline<Document>

`withStage`¶

@DangerousMongoApi
@LowLevelApi
abstract fun withStage(stage: BsonNode): Pipeline<Document>

`writeTo`¶

@LowLevelApi
abstract fun writeTo(writer: BsonValueWriter)