object-id.txt

.. _objectid:

========
ObjectId
========

.. default-domain:: mongodb

Overview
--------

:term:`ObjectId <objectid>` is a 12-byte :term:`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
:term:`_id` field that acts as a :term:`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 :program:`mongod` receives a document to
insert that does not contain an ``_id`` field, :program:`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 :program:`mongo` shell, you can access the creation time of
  the ``ObjectId``, using the :method:`~ObjectId.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 :doc:`/core/document/` section for related
information on MongoDB's document orientation.

.. _core-object-id-class:

ObjectId()
----------

The :program:`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.

- :method:`~ObjectId.getTimestamp()`

  Returns the timestamp portion of the object as a Date.

- :method:`~ObjectId.toString()`

  Returns the JavaScript representation in the form of a string literal
  "``ObjectId(...)``".

  .. versionchanged:: 2.2
     In previous versions :method:`~ObjectId.toString()` returns the
     hexadecimal string representation, which as of version 2.2 can be
     retrieved by the ``str`` property.

- :method:`~ObjectId.valueOf()`

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

  .. versionchanged:: 2.2
     In previous versions, :method:`~ObjectId.valueOf()` returns the
     object.

Examples
--------

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

Generate a new ObjectId
~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: javascript

   x = ObjectId()

In this example, the value of ``x`` would be:

.. code-block:: javascript

   ObjectId("507f1f77bcf86cd799439011")

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

.. code-block:: javascript

   y = ObjectId("507f191e810c19729de860ea")

In this example, the value of ``y`` would be:

.. code-block:: javascript

   ObjectId("507f191e810c19729de860ea")

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

Convert an ObjectId into a Timestamp
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: javascript

   ObjectId("507f191e810c19729de860ea").getTimestamp()

This operation will return the following Date object:

.. code-block:: javascript

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

Convert ObjectIds into Strings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: javascript

   ObjectId("507f191e810c19729de860ea").str

This operation will return the following hexadecimal string:

.. code-block:: none

   507f191e810c19729de860ea

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

.. code-block:: javascript

   ObjectId("507f191e810c19729de860ea").valueOf()

This operation returns the following output:

.. code-block:: none

   507f191e810c19729de860ea

To return the string representation of an ``ObjectId()`` object (in the
form of a string literal ``ObjectId(...)``), use the
:method:`~ObjectId.toString()` method as follows:

.. code-block:: javascript

   ObjectId("507f191e810c19729de860ea").toString()

This operation will return the following string output:

.. code-block:: javascript

   ObjectId("507f191e810c19729de860ea")