diff --git a/source/applications.txt b/source/applications.txt index f9e2a45d04b..e440228baee 100644 --- a/source/applications.txt +++ b/source/applications.txt @@ -32,6 +32,7 @@ The following documents outline basic application development topics: applications/drivers applications/database-references + core/ObjectId .. seealso:: diff --git a/source/core/ObjectId.txt b/source/core/ObjectId.txt new file mode 100644 index 00000000000..104bb94111c --- /dev/null +++ b/source/core/ObjectId.txt @@ -0,0 +1,111 @@ +======== +ObjectId +======== + +:term:`ObjectId ` is a 12-byte :term:`BSON` type that consists of: + +- 4-byte timestamp +- 3-byte machine id +- 2-byte process id +- 3-byte counter + +In MongoDB, documents stored in a collection require a unique +:term:`_id` field that acts as a :term:`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; i.e., the :program:`mongod` adds +the ``_id`` field and generates a unique ``ObjectId`` to assign as its +value. + +Since the ``ObjectId`` contains the timestamp of its generation, using +the ``ObjectId`` as the default value for the ``_id`` field provides +these additional benefits: + +- Storing of the create timestamp is inherent and easily accessible + with the ``getTimestamp()`` method. + +- Sorting by the ``_id`` field is analogous to sorting by the create + timestamp. + +.. _core-object-id-class: + +ObjectId() +---------- + +MongoDB provides the ``ObjectId()`` wrapper class in the :program:`mongo` +shell. The ``ObjectId()`` class can generate a new ``ObjectId`` and 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(...)". + + Prior to version 2.2, returns the value of the object as a + hexadecmial string. + +- ``valueOf()`` + + Returns the value of the ObjectId() object as a hexadecimal string. + The returned string is the ``str`` attribute. + + Prior to version 2.2, returns the object ObjectId(...) + +Consider the following usage of the ObjectID() class in the :program:`mongo` +shell: + +- Generate a new ObjectId() using the constructor with no argument: + + .. code-block:: javascript + + > x = ObjectId() + + ObjectId("507f1f77bcf86cd799439011") + +- Generate a new ObjectId() using the constructor with a unique hexadecimal string: + + .. code-block:: javascript + + > y = ObjectId("507f191e810c19729de860ea") + + ObjectId("507f191e810c19729de860ea") + +- Get the timestamp of an ObjectId() object: + + .. code-block:: javascript + + > ObjectId("507f191e810c19729de860ea").getTimestamp() + + ISODate("2012-10-17T20:46:22Z") + +- Access the ``str`` attribute of an ObjectId() object: + + .. code-block:: javascript + + > ObjectId("507f191e810c19729de860ea").str + + 507f191e810c19729de860ea + +- Get the string representation of an ObjectId() object: + + .. code-block:: javascript + + > ObjectId("507f191e810c19729de860ea").toString() + + ObjectId("507f191e810c19729de860ea") + +- Get the value of an ObjectId() object as a hexadecimal string: + + .. code-block:: javascript + + > ObjectId("507f191e810c19729de860ea").valueOf() + + 507f191e810c19729de860ea diff --git a/source/reference/method/ObjectId.getTimestamp.txt b/source/reference/method/ObjectId.getTimestamp.txt new file mode 100644 index 00000000000..f98fec86b9b --- /dev/null +++ b/source/reference/method/ObjectId.getTimestamp.txt @@ -0,0 +1,21 @@ +======================= +ObjectId.getTimestamp() +======================= + +.. default-domain:: mongodb + +.. method:: ObjectId.getTimestamp() + + Returns the timestamp portion of the :ref:`ObjectId() + ` object as a Date. + + In the following example, the :method:`getTimestamp + ` method for + ``ObjectId("507c7f79bcf86cd7994f6c0e")`` returns + ``ISODate("2012-10-15T21:26:17Z")``: + + .. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").getTimestamp() + + ISODate("2012-10-15T21:26:17Z") diff --git a/source/reference/method/ObjectId.toString.txt b/source/reference/method/ObjectId.toString.txt new file mode 100644 index 00000000000..24d42628338 --- /dev/null +++ b/source/reference/method/ObjectId.toString.txt @@ -0,0 +1,35 @@ +=================== +ObjectId.toString() +=================== + +.. default-domain:: mongodb + +.. method:: ObjectId.toString() + + .. versionchanged:: 2.2 + + Returns the string representation of the :ref:`ObjectId() + ` object and has the format ``ObjectId(...)``. + + In the following example, the :method:`toString + ` method for + ``ObjectId("507c7f79bcf86cd7994f6c0e")`` returns the string literal + ``ObjectId("507c7f79bcf86cd7994f6c0e")``: + + .. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + ObjectId("507c7f79bcf86cd7994f6c0e") + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + string + + .. note:: + + Prior to version 2.2, the :method:`toString + ` method returns the value of the object as + a hexadecmial string, e.g. ``507c7f79bcf86cd7994f6c0e``. More + precisely, prior to version 2.2, the method returns the ``str`` + attribute of the ObjectId() object. diff --git a/source/reference/method/ObjectId.valueOf.txt b/source/reference/method/ObjectId.valueOf.txt new file mode 100644 index 00000000000..85993eded97 --- /dev/null +++ b/source/reference/method/ObjectId.valueOf.txt @@ -0,0 +1,33 @@ +================== +ObjectId.valueOf() +================== + +.. default-domain:: mongodb + +.. method:: ObjectId.valueOf() + + .. versionchanged:: 2.2 + + Returns the value of the :ref:`ObjectId() ` + object as a lowercase hexadecimal string. More precisely, the method + returns the ``str`` attribute of the ObjectId() object. + + In the following example, the :method:`valueOf ` + method for ``ObjectId("507c7f79bcf86cd7994f6c0e")`` returns the + hexadecimal string ``507c7f79bcf86cd7994f6c0e``: + + .. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + 507c7f79bcf86cd7994f6c0e + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + string + + .. note:: + + Prior to version 2.2, :method:`valueOf ` + method returns the object, e.g. + ``ObjectId("507c7f79bcf86cd7994f6c0e")``. diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index edc1dc3eb84..35bd5a3b704 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -301,6 +301,75 @@ database. See: :issue:`SERVER-6961` for more information. +.. _2.2-ObjectId-toString-valueOf-methods: + +``ObjectId().toString()`` Returns String Literal ``ObjectId("...")`` +```````````````````````````````````````````````````````````````````` + +In version 2.2, the :method:`ObjectId.toString()` method returns the +string representation of the :ref:`ObjectId() ` +object and has the format ``ObjectId("...")``. + +.. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + ObjectId("507c7f79bcf86cd7994f6c0e") + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + string + +Previously, in version 2.0, the method would return the hexadecimal +string. + +.. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + 507c7f79bcf86cd7994f6c0e + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + string + +If compatibility between versions 2.0 and 2.2 is required, use +ObjectId().str, which holds the hexadecimal string value in both +versions. + +``ObjectId().valueOf()`` Returns hexadecimal string +``````````````````````````````````````````````````` + +In version 2.2, the :method:`ObjectId.valueOf()` method returns the +value of the :ref:`ObjectId() ` object as a +lowercase hexadecimal string. + +.. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + 507c7f79bcf86cd7994f6c0e + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + string + +Previously, in version 2.0, the method would return the object. + +.. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + ObjectId("507c7f79bcf86cd7994f6c0e") + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + object + +If compatibility between versions 2.0 and 2.2 is required, use +ObjectId().str, which holds the hexadecimal string value in both +versions. + Behavioral Changes ~~~~~~~~~~~~~~~~~~