ObjectId¶

On this page

Overview
ObjectId()
Examples

Overview¶

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

a 4-byte timestamp,
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:

you can access the timestamp of the ObjectId’s creation, using the getTimestamp() method.
sorting on an _id field that stores ObjectId values is roughly equivalent to sorting by creation time, although this relationship is not strict with ObjectId values generated on multiple systems within a single second.

Also consider the BSON 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.
getTimestamp()

Returns the timestamp portion of the ObjectId() object as a Date.
toString()

Returns the string representation of the ObjectId() object. The returned string literal has the format “ObjectId(...)”.

Changed in version 2.2: In previous versions ObjectId.toString() returns the value of the ObjectId as a hexadecimal string.
valueOf()

Returns the value of the ObjectId() object as a hexadecimal string. The returned string is the str attribute.

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

Examples¶

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

To generate a new ObjectId, use the ObjectId() constructor with no argument:
copy
```
x = ObjectId()
```
In this example, the value of x would be:
copy
```
ObjectId("507f1f77bcf86cd799439011")
```
To generate a new ObjectId using the ObjectId() constructor with a unique hexadecimal string:
copy
```
y = ObjectId("507f191e810c19729de860ea")
```
In this example, the value of y would be:
copy
```
ObjectId("507f191e810c19729de860ea")
```
To return the timestamp of an ObjectId() object, use the getTimestamp() method as follows:
copy
```
ObjectId("507f191e810c19729de860ea").getTimestamp()
```
This operation will return the following Date object:
copy
```
ISODate("2012-10-17T20:46:22Z")
```
Access the str attribute of an ObjectId() object, as follows:
copy
```
ObjectId("507f191e810c19729de860ea").str
```
This operation will return the following hexadecimal string:
copy
```
507f191e810c19729de860ea
```
To return the string representation of an ObjectId() object, use the toString() method as follows:
copy
```
ObjectId("507f191e810c19729de860ea").toString()
```
This operation will return the following output:
copy
```
ObjectId("507f191e810c19729de860ea")
```
To return the value of an ObjectId() object as a hexadecimal string, use the valueOf() method as follows:
copy
```
ObjectId("507f191e810c19729de860ea").valueOf()
```
This operation returns the following output:
copy
```
507f191e810c19729de860ea
```

← BSON Documents Database References →