AggregationPipeline¶

interface AggregationPipeline<Document : Any> : Pipeline<Document> , HasCount<Document> , HasGroup<Document> , HasLimit<Document> , HasMatch<Document> , HasProject<Document> , HasSample<Document> , HasSet<Document> , HasSkip<Document> , HasSort<Document> , HasUnionWith<Document> , HasUnionWithCompatibility<Document> , HasUnset<Document>

An aggregation pipeline.

Aggregation pipelines read data from one or more collections and transform it in a manner of ways. Finally, the data can be sent to the server, or written to another collection.

Example¶

invoices.aggregate()
    .match { Invoice::isDraft eq false }
    .set {
        Invoice::anomaly set (of(Invoice::modificationDate) lt of(Invoice::creationDate))
    }
    .sort { ascending(Invoice::creationDate) }
    .toList()

External resources¶

Official documentation

Properties¶

context¶

@LowLevelApi



abstract val context: BsonContext

The context used to generate this pipeline.

Can be accessed within children expressions.

Functions¶

`countTo`¶

open fun <Output : Any> countTo(field: KProperty1<Output, Number>): Pipeline<Output>

Counts how many elements exist in the pipeline and outputs a single document containing a single field containing the count.

open fun <Output : Any> countTo(field: Field<Output, Number>): Pipeline<Output>

Counts how many elements exist in the pipeline and outputs a single document containing a single field containing the count.

`embedInUnionWith`¶

@LowLevelApi



abstract fun embedInUnionWith(writer: BsonFieldWriter)

Writes this pipeline into a $unionWith stage.

`group`¶

open fun <Out : Any> group(block: AccumulationOperators<Document, Out>.() -> Unit): Pipeline<Out>

Combines multiple documents into a single document.

`limit`¶

open fun limit(amount: Int): Pipeline<Document>

Limits the number of elements passed to the next stage to amount.

open fun limit(amount: Long): Pipeline<Document>

Limits the number of elements passed to the next stage to amount.

`match`¶

open fun match(filter: FilterQuery<Document>.() -> Unit): Pipeline<Document>

Filters documents based on a specified filter.

`project`¶

open fun project(block: ProjectStageOperators<Document>.() -> Unit): Pipeline<Document>

Specifies a list of fields which should be kept in the document.

reinterpret¶

@DangerousMongoApi



@LowLevelApi



abstract fun <New : Any> reinterpret(): Pipeline<New>

Changes the type of the returned document, with no type-safety.

End-users should not need to call this function. This function is provided to allow stages to change the return document. No type verifications are made, it is solely the responsibility of the caller to ensure that the declared return type corresponds to the reality.

See also

Pipeline.withStage: Add a new stage to this pipeline.

`sample`¶

open fun sample(size: Int): Pipeline<Document>

Randomly selects size documents.

`set`¶

open fun set(block: SetStageOperators<Document>.() -> Unit): Pipeline<Document>

Adds new fields to documents, or overwrites existing fields.

`skip`¶

open fun skip(amount: Int): Pipeline<Document>

Skips over the specified amount of documents that pass into the stage, and passes the remaining documents to the next stage.

open fun skip(amount: Long): Pipeline<Document>

Skips over the specified amount of documents that pass into the stage, and passes the remaining documents to the next stage.

`sort`¶

open fun sort(block: SortOptionDsl<Document>.() -> Unit): Pipeline<Document>

Specifies in which order elements should be sorted.

toString¶

abstract override fun toString(): String

JSON representation of this pipeline.

`unionWith`¶

open fun unionWith(other: HasUnionWithCompatibility<Document>): Pipeline<Document>

Combines two aggregations into a single result set.

`unset`¶

open fun unset(block: UnsetStageOperators<Document>.() -> Unit): Pipeline<Document>

Removes fields from documents.

withStage¶

@DangerousMongoApi



@LowLevelApi



abstract fun withStage(stage: BsonNode): Pipeline<Output>

Creates a new pipeline that expands on the current one by adding stage.

This method is analogous to CompoundBsonNode.accept, with the main difference that the latter mutates the current expression, whereas this method returns a new pipeline on which the stage is applied (because pipelines are immutable).

End-users should not need to call this function. All implemented stages provide an extension function on the Pipeline type. This function is provided for cases in which you need a stage that is not yet provided by the library. If that is your situation, start by reading AbstractBsonNode and AbstractCompoundBsonNode. If you want to proceed and implement your own stage, consider getting in touch with the maintainers of the library so it can be shared to all users.

The provided stage must validate the entire contract of BsonNode. Additionally, it should always emit the name of the stage first. For example, this is a valid stage:

"$match": {
    "name": "Bob"
}

but this isn't:

"name": "Bob"

because it doesn't start with a stage name.

Similarly, this isn't a valid stage, because it declares two different stage names:

"$match": {
    "name": "Bob"
},
"$set": {
    "foo": "bar"
}

See also

Pipeline.reinterpret: Change the output type of this pipeline.

writeTo¶

@LowLevelApi



abstract fun writeTo(writer: BsonValueWriter)

Writes the entire pipeline into writer.

This function is similar to BsonNode.writeTo, with the difference that expressions generate documents, and pipelines generate arrays.

Using this method will thus write an array containing the different stages.