From 6d4d6e31d120df5f6a92afd6c18d0f0e2d9364a6 Mon Sep 17 00:00:00 2001 From: Andrew Aldridge Date: Wed, 1 Oct 2014 10:20:55 -0400 Subject: [PATCH] DOCS-4082: Timestamp() update --- source/reference/bson-types.txt | 45 ++++++++++++--------------------- 1 file changed, 16 insertions(+), 29 deletions(-) diff --git a/source/reference/bson-types.txt b/source/reference/bson-types.txt index cc9d4558dab..b21266f9b8c 100644 --- a/source/reference/bson-types.txt +++ b/source/reference/bson-types.txt @@ -81,44 +81,31 @@ value. .. note:: - The BSON Timestamp type is for *internal* MongoDB use. For most + The BSON timestamp type is for *internal* MongoDB use. For most cases, in application development, you will want to use the BSON date type. See :ref:`document-bson-type-date` for more information. -If you create a BSON Timestamp using the empty constructor (e.g. ``new -Timestamp()``), MongoDB will only generate a timestamp *if* you use -the constructor in the first field of the document. [#id_exception]_ -Otherwise, MongoDB will generate an empty timestamp value -(i.e. ``Timestamp(0, 0)``.) +If you insert a document containing an empty BSON timestamp in a top-level +field, the MongoDB server will replace that empty timestamp with the current +timestamp value. For example, -.. versionchanged:: 2.1 - :program:`mongo` shell displays the Timestamp value with the wrapper: +.. code-block:: javascript - .. code-block:: javascript - - Timestamp(, ) - - Prior to version 2.1, the :program:`mongo` shell display the - Timestamp value as a document: - - .. code-block:: javascript - - { t : , i : } - -.. [#id_exception] If the first field in the document is ``_id``, then - you can generate a timestamp in the *second* field - of a document. - - .. only:: html or dirhtml or singlehtml or epub or gettext + > var a = new Timestamp(); a; + Timestamp(0, 0) - In the following example, MongoDB will generate a Timestamp - value, even though the ``Timestamp()`` constructor is *not* in - the first field in the document: + > db.test.insert( { ts: a } ); + > db.test.find(); + { "_id" : ObjectId("542c2b97bac0595474108b48"), "ts" : Timestamp(1412180887, 1) } - .. code-block:: javascript +If ``ts`` were a field in an embedded document, the server would have left it as an +empty timestamp value. - db.bios.insert( { _id: 9, last_updated: new Timestamp() } ) +.. versionchanged:: 2.6 + Previously, the server would only replace empty timestamp values in the first + two fields, including ``_id``, of an inserted document. Now MongoDB will + replace any top-level field. .. _document-bson-type-date: