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

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