Skip to content

ObjectId

@Serializable
(with = ObjectId.Serializer::class)class ObjectId : Comparable<ObjectId>

Small, likely unique, fast to generate, ordered identifier.

  • Small: Each ObjectId is 12 bytes long, shorter than a UUID's 16 bytes.

  • Likely unique: Each driver randomly selects a generation range, so conflicts are unlikely.

  • Fast to generate: Depending on the generation strategy, generating a new ObjectId may be as simple as querying the time and incrementing a counter.

  • Ordered: All ObjectId instances can be sorted by creating date, with a precision of one second. Two ObjectId instances created by the same driver are sorted with even more precision.

Composition

An ObjectId is composed of:

  • A 4-byte timestamp, representing the ObjectId's creation date, with a precision of one second,

  • A 5-byte random processId, unique to each machine and process, to decrease conflicts,

  • A 3-byte incrementing counter, initialized at a random value.

ObjectId instances are generally represented as 24-characters hexadecimal strings:

ObjectId("699dfad90ca573f85c0eec1c").hex // 699dfad90ca573f85c0eec1c

Generating new ObjectIds

There are different strategies to generate new ObjectId instances; they are encoded by the ObjectIdGenerator interface.

The ObjectIdGenerator used by each driver is available directly on each collection:

users.insert(
    User(
        _id = users.newId(), // Generate an ObjectId using the configuration specific to that collection
        name = "Bob",
    )
)

External resources

Thread safety

Instances of this class are immutable and thread-safe.

Constructors

ObjectId

constructor(
    timestamp: Instant, 
    processId: Long, 
    counter: Int
)

Constructs a new ObjectId from its different components.

constructor(bytes: ByteArray)

Constructs a new ObjectId by reading a byte array.

bytes should be exactly 12-bytes long.

To access the bytes of an existing ObjectId, see ObjectId.bytes.

constructor(hex: String)

Constructs a new ObjectId by reading a hexadecimal representation.

hex should be exactly 24 characters long (12 bytes).

To access the hexadecimal representation of an existing ObjectId, see ObjectId.hex.

Types

Companion

object Companion

Serializer

@LowLevelApi



object Serializer : KSerializer<ObjectId>

Default serializer for ObjectId.

Properties

bytes

Generates a byte representation of this ObjectId instance.

Because ByteArray is mutable, each access will generate a new array.

The output array can be passed to the ObjectId constructor to obtain a new identical ObjectId instance.

counter

val counter: Int

A 3-byte incrementing counter per client-side process, initialized to a random value. Always positive.

The counter resets when a process restarts.

Example
ObjectId("699dfad90ca573f85c0eec1c").counter // 977948

See also

hex

val hex: String

Generates a hex representation of this ObjectId instance.

The output string can be passed to ObjectId constructor to obtain a new identical ObjectId instance.

processId

5-byte random value generated per client-side process.

This random value is unique to the machine and process. If the process restarts of the primary node of the process changes, this value is re-regenerated.

Example
ObjectId("699dfad90ca573f85c0eec1c").processId // 54315448412

See also

timestamp

The ObjectId creation timestamp, with a resolution of one second.

This timestamp can represent time from the UNIX epoch (Jan 1 1970) and is stored as 32 unsigned bits (approximately Feb 2 2106, see ObjectId.MAX's timestamp for an exact value).

Example
ObjectId("699dfad90ca573f85c0eec1c").timestamp // 2026-02-24T19:24:09Z

Functions

compareTo

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

operator fun compareTo(other: Instant): Int

equals

open operator override fun equals(other: Any?): Boolean

hashCode

open override fun hashCode(): Int

toString

open override fun toString(): String