Skip to content

Path

@LowLevelApi
data class Path(val segment: PathSegment, val parent: Path?) : Comparable<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)].

compareTo

open operator override fun compareTo(other: Path): Int

Compares this path with another path.

The paths are compared based on order when walking a filesystem:

  • The paths are compared by their length, with shorter paths being considered "less than" longer paths.

  • If the paths have the same length, they are compared by their segments, in order. The comparison is done by comparing the segment types first, and then the segment values (in alphanumérical order).

Therefore, this is a possible order:

a
a.b
a.foo
a.foo.bar
a.foo.baz
d
d.1
d.2

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