OPTIONS

ObjectId

Overview

ObjectId is a 12-byte BSON type, constructed using:

  • a 4-byte value representing the seconds since the Unix epoch,
  • a 3-byte machine identifier,
  • a 2-byte process id, and
  • a 3-byte counter, starting with a random value.

In MongoDB, documents stored in a collection require a unique _id field that acts as a primary key. Because ObjectIds are small, most likely unique, and fast to generate, MongoDB uses ObjectIds as the default value for the _id field if the _id field is not specified. MongoDB clients should add an _id field with a unique ObjectId. However, if a client does not add an _id field, mongod will add an _id field that holds an ObjectId.

Using ObjectIds for the _id field provides the following additional benefits:

  • in the mongo shell, you can access the creation time of the ObjectId, using the getTimestamp() method.

  • sorting on an _id field that stores ObjectId values is roughly equivalent to sorting by creation time.

    Important

    The relationship between the order of ObjectId values and generation time is not strict within a single second. If multiple systems, or multiple processes or threads on a single system generate values, within a single second; ObjectId values do not represent a strict insertion order. Clock skew between clients can also result in non-strict ordering even for values, because client drivers generate ObjectId values, not the mongod process.

Also consider the Documents section for related information on MongoDB’s document orientation.

ObjectId()

The mongo shell provides the ObjectId() wrapper class to generate a new ObjectId, and to provide the following helper attribute and methods:

  • str

    The hexadecimal string representation of the object.

  • getTimestamp()

    Returns the timestamp portion of the object as a Date.

  • toString()

    Returns the JavaScript representation in the form of a string literal “ObjectId(...)”.

    Changed in version 2.2: In previous versions toString() returns the hexadecimal string representation, which as of version 2.2 can be retrieved by the str property.

  • valueOf()

    Returns the representation of the object as a hexadecimal string. The returned string is the str attribute.

    Changed in version 2.2: In previous versions, valueOf() returns the object.

Examples

Consider the following uses ObjectId() class in the mongo shell:

Generate a new ObjectId

To generate a new ObjectId, use the ObjectId() constructor with no argument:

x = ObjectId()

In this example, the value of x would be:

ObjectId("507f1f77bcf86cd799439011")

To generate a new ObjectId using the ObjectId() constructor with a unique hexadecimal string:

y = ObjectId("507f191e810c19729de860ea")

In this example, the value of y would be:

ObjectId("507f191e810c19729de860ea")
  • To return the timestamp of an ObjectId() object, use the getTimestamp() method as follows:

Convert an ObjectId into a Timestamp

To return the timestamp of an ObjectId() object, use the getTimestamp() method as follows:

ObjectId("507f191e810c19729de860ea").getTimestamp()

This operation will return the following Date object:

ISODate("2012-10-17T20:46:22Z")

Convert ObjectIds into Strings

Access the str attribute of an ObjectId() object, as follows:

ObjectId("507f191e810c19729de860ea").str

This operation will return the following hexadecimal string:

507f191e810c19729de860ea

To return the hexadecimal string representation of an ObjectId(), use the valueOf() method as follows:

ObjectId("507f191e810c19729de860ea").valueOf()

This operation returns the following output:

507f191e810c19729de860ea

To return the string representation of an ObjectId() object, use the toString() method as follows:

ObjectId("507f191e810c19729de860ea").toString()

This operation will return the following output:

ObjectId("507f191e810c19729de860ea")