- Data Models >
- Data Model Reference >
- ObjectId
ObjectId¶
On this page
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. MongoDB uses
ObjectIds as the default value for the _id
field if the _id
field is not specified; i.e. if a document does not contain a top-level
_id
field, the MongoDB driver adds the _id
field that holds an
ObjectId. In addition, if the mongod
receives a document to
insert that does not contain an _id
field, mongod
will
add the _id
field that holds an ObjectId.
MongoDB clients should add an _id
field with a unique ObjectId.
Using ObjectIds for the _id
field provides the following additional
benefits:
in the
mongo
shell, you can access the creation time of theObjectId
, using thegetTimestamp()
method.sorting on an
_id
field that storesObjectId
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 generateObjectId
values.
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 value of the
ObjectId()
object.-
Returns the timestamp portion of the
ObjectId()
object as a Date. -
Returns the string representation of the
ObjectId()
object. The returned string literal has the format “ObjectId(...)
”.Changed in version 2.2: In previous versions
toString()
returns the value of the ObjectId as a hexadecimal string. -
Returns the value of the
ObjectId()
object as a hexadecimal string. The returned string is thestr
attribute.Changed in version 2.2: In previous versions
valueOf()
returns theObjectId()
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:
In this example, the value of x
would be:
To generate a new ObjectId using the ObjectId()
constructor with
a unique hexadecimal string:
In this example, the value of y
would be:
- To return the timestamp of an
ObjectId()
object, use thegetTimestamp()
method as follows:
Convert an ObjectId into a Timestamp¶
To return the timestamp of an ObjectId()
object, use the
getTimestamp()
method as follows:
This operation will return the following Date object:
Convert ObjectIds into Strings¶
Access the str
attribute of an ObjectId()
object, as follows:
This operation will return the following hexadecimal string:
To return the value of an ObjectId()
object as a hexadecimal
string, use the valueOf()
method as
follows:
This operation returns the following output:
To return the string representation of an ObjectId()
object, use
the toString()
method as follows:
This operation will return the following output: