- 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 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.
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 the str 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:
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 (in the form of a string literal ObjectId(...)), use the toString() method as follows:
ObjectId("507f191e810c19729de860ea").toString()
This operation will return the following string output:
ObjectId("507f191e810c19729de860ea")
Thank you for your feedback!
We're sorry! You can Report a Problem to help us improve this page.