AggregationPipeline¶

interface AggregationPipeline<Document : Any> : Pipeline<Document> , HasCount<Document> , HasGroup<Document> , HasLimit<Document> , HasLookup<Document> , HasLookupPipelineCompatibility<Document> , HasMatch<Document> , HasProject<Document> , HasSample<Document> , HasSet<Document> , HasSkip<Document> , HasSort<Document> , HasUnionWith<Document> , HasUnionWithCompatibility<Document> , HasUnset<Document> , HasUnwind<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.

`embedInLookup`¶

@LowLevelApi
abstract fun embedInLookup(writer: BsonFieldWriter)

Writes this pipeline's contribution into a $lookup stage.

`embedInUnionWith`¶

@LowLevelApi
abstract fun embedInUnionWith(writer: BsonFieldWriter)

Writes this pipeline into a $unionWith stage.

`group`¶

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

Combines many documents into few documents.

`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.

`lookup`¶

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

Performs an equality match join between this collection and another collection.

`match`¶

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

Filters documents based on a specified filter.

`matchExpr`¶

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

Filters documents based on a specific filter, written using aggregation syntax.

`project`¶

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

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

`set`¶

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

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.

unsafeCast¶

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

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

Every subsequent step in the pipeline will think the returned document is of type New. It is your responsibility to ensure that this corresponds to the reality; the KtMongo DSL makes no verifications.

If you want to edit the representation of the documents in the pipeline, prefer using HasProject.project.

See also

withStage: Add a new stage to this pipeline.

`unset`¶

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

Removes fields from documents.

`unwind`¶

open fun <Item, Out : Any> unwind(block: UnwindStageOperators<Document, Item, Out>.() -> Unit): Pipeline<Out>

Unwinds an array.

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

unsafeCast: 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.