diff --git a/config/redirects.yaml b/config/redirects.yaml index a254426fce1..db3dffb6d85 100644 --- a/config/redirects.yaml +++ b/config/redirects.yaml @@ -431,6 +431,13 @@ code: 301 outputs: - 'before-v2.6' --- +from: '/reference/method/cursor.showDiskLoc' +to: '/reference/method/cursor.showRecordId' +type: 'redirect' +code: 301 +outputs: + - 'after-v3.0' +--- from: '/reference/method/setVerboseShell' to: '/reference/method' type: 'redirect' @@ -902,4 +909,4 @@ code: 303 outputs: - 'before-v3.0' - 'manual' -... \ No newline at end of file +... diff --git a/source/includes/example-showDiskLoc.rst b/source/includes/example-showDiskLoc.rst deleted file mode 100644 index 92f02dd16d2..00000000000 --- a/source/includes/example-showDiskLoc.rst +++ /dev/null @@ -1,46 +0,0 @@ -The following operation appends the :method:`~cursor.showDiskLoc()` -method to the :method:`db.collection.find()` method in order to include -in the matching documents the disk location information: - -.. code-block:: javascript - - db.collection.find( { a: 1 } ).showDiskLoc() - -The operation returns the following documents, which includes the -``$diskLoc`` field: - -.. code-block:: javascript - - { - "_id" : ObjectId("53908ccb18facd50a75bfbac"), - "a" : 1, - "b" : 1, - "$diskLoc" : { "file" : 0, "offset" : 16195760 } - } - { - "_id" : ObjectId("53908cd518facd50a75bfbad"), - "a" : 1, - "b" : 2, - "$diskLoc" : { "file" : 0, "offset" : 16195824 } - } - -The :term:`projection` can also access the added field ``$diskLoc``, -as in the following example: - -.. code-block:: javascript - - db.collection.find( { a: 1 }, { $diskLoc: 1 } ).showDiskLoc() - -The operation returns just the ``_id`` field and the ``$diskLoc`` -field in the matching documents: - -.. code-block:: javascript - - { - "_id" : ObjectId("53908ccb18facd50a75bfbac"), - "$diskLoc" : { "file" : 0, "offset" : 16195760 } - } - { - "_id" : ObjectId("53908cd518facd50a75bfbad"), - "$diskLoc" : { "file" : 0, "offset" : 16195824 } - } diff --git a/source/includes/example-showRecordId.rst b/source/includes/example-showRecordId.rst new file mode 100644 index 00000000000..66834236073 --- /dev/null +++ b/source/includes/example-showRecordId.rst @@ -0,0 +1,46 @@ +The following operation appends the :method:`~cursor.showRecordId()` +method to the :method:`db.collection.find()` method in order to include +storage engine record information in the matching documents: + +.. code-block:: javascript + + db.collection.find( { a: 1 } ).showRecordId() + +The operation returns the following documents, which include the ``$recordId`` +field: + +.. code-block:: javascript + + { + "_id" : ObjectId("53908ccb18facd50a75bfbac"), + "a" : 1, + "b" : 1, + "$recordId" : NumberLong(168112) + } + { + "_id" : ObjectId("53908cd518facd50a75bfbad"), + "a" : 1, + "b" : 2, + "$recordId" : NumberLong(168176) + } + +You can :term:`project ` the added field ``$recordId``, as in the +following example: + +.. code-block:: javascript + + db.collection.find( { a: 1 }, { $recordId: 1 } ).showRecordId() + +This query returns only the ``_id`` field and the ``$recordId`` +field in the matching documents: + +.. code-block:: javascript + + { + "_id" : ObjectId("53908ccb18facd50a75bfbac"), + "$recordId" : NumberLong(168112) + } + { + "_id" : ObjectId("53908cd518facd50a75bfbad"), + "$recordId" : NumberLong(168176) + } diff --git a/source/includes/ref-toc-method-cursor.yaml b/source/includes/ref-toc-method-cursor.yaml index c55e4e5c281..efbd786dfc3 100644 --- a/source/includes/ref-toc-method-cursor.yaml +++ b/source/includes/ref-toc-method-cursor.yaml @@ -66,9 +66,9 @@ name: ":method:`cursor.readPref()`" file: /reference/method/cursor.readPref description: "Specifies a :term:`read preference` to a cursor to control how the client directs queries to a :term:`replica set`." --- -name: ":method:`cursor.showDiskLoc()`" -file: /reference/method/cursor.showDiskLoc -description: "Returns a cursor with modified documents that include the on-disk location of the document." +name: ":method:`cursor.showRecordId()`" +file: /reference/method/cursor.showRecordId +description: "Adds an internal storage engine ID field to each document returned by the cursor." --- name: ":method:`cursor.size()`" file: /reference/method/cursor.size diff --git a/source/reference/method/cursor.showDiskLoc.txt b/source/reference/method/cursor.showDiskLoc.txt deleted file mode 100644 index d8e178b2c85..00000000000 --- a/source/reference/method/cursor.showDiskLoc.txt +++ /dev/null @@ -1,33 +0,0 @@ -==================== -cursor.showDiskLoc() -==================== - -.. default-domain:: mongodb - -.. method:: cursor.showDiskLoc() - - Modifies the output of a query by adding a field ``$diskLoc`` to - matching documents. ``$diskLoc`` contains disk location information - and has the form: - - .. code-block:: javascript - - "$diskLoc": { - "file": , - "offset": - } - - :method:`cursor.showDiskLoc()` method is a wrapper around - :operator:`$showDiskLoc`. - - :returns: A modified cursor object that contains documents with - appended information that describes the on-disk location - of the document. - -Example -------- - -.. include:: /includes/example-showDiskLoc.rst - -.. seealso:: :operator:`$showDiskLoc` for related - functionality. diff --git a/source/reference/method/cursor.showRecordId.txt b/source/reference/method/cursor.showRecordId.txt new file mode 100644 index 00000000000..d6912ece848 --- /dev/null +++ b/source/reference/method/cursor.showRecordId.txt @@ -0,0 +1,26 @@ +===================== +cursor.showRecordId() +===================== + +.. default-domain:: mongodb + +.. method:: cursor.showRecordId() + + .. versionchanged:: 3.2 + This method replaces the previous ``cursor.showDiskLoc()``. + + Modifies the output of a query by adding a field ``$recordId`` to + matching documents. ``$recordId`` is the internal key which uniquely + identifies a document in a collection. It has the form: + + .. code-block:: javascript + + "$recordId": NumberLong() + + :returns: A modified cursor object that contains documents with + appended information describing the internal record key. + +Example +------- + +.. include:: /includes/example-showRecordId.rst diff --git a/source/reference/operator/meta/showDiskLoc.txt b/source/reference/operator/meta/showDiskLoc.txt index 3c695283a3a..fd56cac265c 100644 --- a/source/reference/operator/meta/showDiskLoc.txt +++ b/source/reference/operator/meta/showDiskLoc.txt @@ -6,33 +6,6 @@ $showDiskLoc .. operator:: $showDiskLoc - :operator:`$showDiskLoc` option adds a field ``$diskLoc`` to the - returned documents. The value of the added ``$diskLoc`` field is a - document that contains the disk location information: - - .. code-block:: javascript - - "$diskLoc": { - "file": , - "offset": - } - - The :program:`mongo` shell provides the - :method:`cursor.showDiskLoc()` method for :operator:`$showDiskLoc`: - - .. code-block:: javascript - - db.collection.find().showDiskLoc() - - You can also specify the :operator:`$showDiskLoc` option in either - of the following forms: - - .. code-block:: javascript - - db.collection.find( { } )._addSpecial("$showDiskLoc" , true) - db.collection.find( { $query: { }, $showDiskLoc: true } ) - -Example -------- - -.. include:: /includes/example-showDiskLoc.rst + .. deprecated:: 3.2 + The :operator:`$showDiskLoc` operator is deprecated. Instead use the + :method:`cursor.showRecordId()` method. diff --git a/source/release-notes/3.2-compatibility.txt b/source/release-notes/3.2-compatibility.txt index 31626aefb7d..fab2310f5dd 100644 --- a/source/release-notes/3.2-compatibility.txt +++ b/source/release-notes/3.2-compatibility.txt @@ -80,7 +80,7 @@ can drop and recreate the index: use test db.legacyOrders.dropIndex( "x_1" ) - or by key: + or by key: .. code-block:: javascript @@ -149,6 +149,11 @@ Driver Compatibility Changes A driver upgrade is necessary to support :dbcommand:`find` and :dbcommand:`getMore`. +General Compatibility Changes +----------------------------- + +In MongoDB 3.2, ``cursor.showDiskLoc()`` is deprecated in favor of +:method:`cursor.showRecordId()`, and both return a new document format. Additional Information ----------------------