withStage

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