Skip to content

Path

@LowLevelApi
data class Path(val segment: PathSegment, val parent: Path?)

Low-level, type-unsafe pointer to a specific field in a document.

A path is a string pointer that identifies which field(s) are impacted by an operator.

For example, the following are valid paths:

  • "foo": targets the field "foo",

  • "foo.bar": targets the field "bar" which is part of the object "foo",

  • "arr.5.bar": targets the field "bar" which is part of the item with index 5 in the array "arr".

This structure is a singly-linked list representing the entire path. Each segment is represented by PathSegment.

The high-level type-safe equivalent of this type is Field.

Constructors

Path

constructor(segment: PathSegment, parent: Path?)

Path

@LowLevelApi
fun Path(root: String): Path

Creates a root path from the provided root field name.

To obtain children instances, use the div operator.

Types

Companion

object Companion

Properties

parent

val parent: Path?

The previous link in this Path.

For example, the path Path(PathSegment.Indexed(5), Path(PathSegment.Field("foo"), null)) represents the path "foo.5".

segment

Functions

asSequence

Returns a Sequence of the different PathSegment instances that form this Path, in hierarchical order.

For example, the path Path(PathSegment.Indexed(5), Path(PathSegment.Field("foo"), null)) represents the path "foo.5" and would return the sequence [PathSegment.Field("foo"), PathSegment.Indexed(5)].

div

@LowLevelApi
operator fun Path.div(segment: PathSegment): Path

Returns a new Path instance that is the concatenation of the current path and a segment.

@LowLevelApi
@DangerousMongoApi
operator fun Path.div(path: Path): Path

Returns a new Path instance that is the concatenation of the current path and a child path.

Danger. This API does not check that path makes sense as a child of the current path!

toBsonPath

Converts this MongoDB Path to a BsonPath.

BsonPath is an implementation of RFC9535 JSONPath. See its documentation for more information.

fun Field<*, *>.toBsonPath(): BsonPath

Converts this MongoDB Field to a BsonPath.

BsonPath is an implementation of RFC9535 JSONPath. See its documentation for more information.

BsonPath can be useful to access elements from an arbitrary BSON document, for example, after a projection.

Example

data class User(
    val _id: ObjectId,
    val profile: Profile,
)

data class Profile(
    val name: String,
)

val fieldName = (User::profile / Profile::name).toBsonPath()

val bson: Bson = …
val name = bson at fieldName

See also

  • select: Select multiple values.

  • selectFirst: Select the first value.

  • at: Select the first value, as an infix operator.

toString

open override fun toString(): String

Returns the string representation of this Path. This is the representation that is sent to MongoDB to refer to a Field.

For example, the path Path(PathSegment.Indexed(5), Path(PathSegment.Field("foo"), null)) represents the path "foo.5".