- 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 representation of the object.
-
Returns the timestamp portion of the object as a Date.
-
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 thestr
property. -
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:
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 hexadecimal string representation of an ObjectId()
,
use the valueOf()
method as follows:
This operation returns the following output:
To return the string representation of an ObjectId()
object (in the
form of a string literal ObjectId(...)
), use the
toString()
method as follows:
This operation will return the following string output: