HasProject¶

interface HasProject<Document : Any> : Pipeline<Document>

Pipeline implementing the $project stage.

Inheritors¶

Properties¶

`context`¶

@LowLevelApi



abstract val context: BsonContext

The context used to generate this pipeline.

Functions¶

project¶

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

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

All fields (except _id) that are not specified in this stage are unset.

_id is kept even if not specified. To exclude it, see ProjectStageOperators.excludeId.

Difference with MongoDB¶

In BSON, the $project stage can be used either for declaring an allow-list (by including fields, and possibly excluding the _id) or a block-list (by excluding fields). MongoDB doesn't allow a single stage usage to mix both usages.

Because this is confusing, KtMongo splits both of these use-cases into two different methods. The former (selecting fields we want to keep) is performed by this method. The latter (selecting fields we want to remove) is performed by the stage $unset.

Note that just like in MongoDB, this stage can use all operators of the `$set stage`.

Difference with $set¶

This stage and the `$set stage` are quite similar. In fact, both stages behave the same for fields that are specified.

However, the stages behave differently for fields that are not specified:

$project removes all fields that are not explicitly specified.
$set does not impact fields that are not explicitly specified, they are left in the exact same state as previously.

Performance¶

When you use a $project stage it should typically be the last stage in your pipeline, used to specify which fields to return to the client.

Using a $project stage at the beginning or middle of a pipeline to reduce the number of fields passed to subsequent pipeline stages is unlikely to improve performance, as the database performs this optimization automatically.

Example¶

class User(
    val name: String,
    val year: Int?,
)

users.aggregate()
    .project {
        include(User::name)
    }
    .toList()

In this example, the year field will not be returned by the aggregation, because it is not mentioned in the $project stage.

External resources¶

Official documentation

`reinterpret`¶

@DangerousMongoApi



@LowLevelApi



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

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

`toString`¶

abstract override fun toString(): String

JSON representation of this pipeline.

`withStage`¶

@DangerousMongoApi



@LowLevelApi



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

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

`writeTo`¶

@LowLevelApi



abstract fun writeTo(writer: BsonValueWriter)

Writes the entire pipeline into writer.