DOCS-654 new 2.0 index format

Author: Bob Grabar

source/release-notes/2.0.txt

@@ -24,8 +24,7 @@ Read through all release notes before upgrading, and ensure that no
 changes will affect your deployment.
 
 If you create new indexes in 2.0, then downgrading to 1.8 is possible
-but you must reindex the new collections. For more information on 2.0
-indexes and on rollback, see :wiki:`Index Versions`.
+but you must reindex the new collections.
 
 :program:`mongoimport` and :program:`mongoexport` now correctly adhere to the CSV spec
 for handling CSV input/output. This may break existing import/export
@@ -43,6 +42,26 @@ In addition, you may see reduced write throughput.
 :program:`mongod` instances; however, for best results, upgrade your
 deployments using the following procedures:
 
+.. _2.0-convert-to-new-index-format:
+
+Converting an Existing Index to the New Format
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To convert all indexes for a given collection to the
+:ref:`2.0 type <2.0-new-index-format>`, invoke the
+:doc:`compact </reference/command/compact>` command.
+
+All operations that create a new index will result in a 2.0 index by
+default. For example:
+
+- Reindexing results on an older-version index results in a 2.0 index.
+  However, reindexing on a secondary does *not* work in versions prior
+  to 2.0. Do not reindex on a secondary. For a workaround, see
+  :issue:`SERVER-3866`.
+
+- The :setting:`repair` database command converts indexes to a 2.0
+  indexes.
+
 .. _2.0-upgrade-standalone:
 
 Upgrading a Standalone ``mongod``
@@ -130,6 +149,8 @@ swapped out if unused, some operating systems do this slowly enough that
 it might be an issue. The default stack size is lesser of the
 system setting or 1MB.
 
+.. _2.0-new-index-format:
+
 Index Performance Enhancements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -145,6 +166,8 @@ from 819 to 1024 bytes.
 Once you create new indexes, downgrading to 1.8.x will require a
 re-index of any indexes created using 2.0.
 
+.. seealso:: :ref:`2.0-convert-to-new-index-format`
+
 Sharding Authentication
 ~~~~~~~~~~~~~~~~~~~~~~~
 

source/tutorial/roll-back-to-v18-index.txt

@@ -0,0 +1,46 @@
+================================
+Roll Back to a Version 1.8 Index
+================================
+
+.. default-domain:: mongodb
+
+
+MongoDB version 2.0 and later supports the old index format. But old versions
+will not support the new format. If you need to roll back to an older
+version, the server will run, but queries and other operations involving
+the newer indexes will log and return an error. Thus, you will need to
+re-create any new index you would like to use on an old server.
+
+Versions prior to 1.8.2, inclusive, are not aware of the index version
+field. If you rollback a ``{v:1}`` index to 1.8.2 and re-index it, its
+version will still be marked ``{v: 1}``, although it actual is now version ``{v:0}``.
+If you upgrade again to 2.0, this index will not work, even though it is
+marked as ``{v: 1}`` in ``system.indexes``. If you must roll back to a
+version prior to 1.8.2, you must delete the index then create it again
+(instead of simply re-indexing).
+
+Building a {v:0} Index
+----------------------
+
+You can still create a ``{v:0}`` index with MongoDB version 2.0 or later. To do so, add the
+option ``{v:0}`` in the index creation command. For example in the :program:`mongo`
+shell:
+
+.. code-block:: javascript
+
+   // defaults to a v:1 index
+   db.foo.ensureIndex({name:1})
+   db.system.indexes.find()
+   { "v" : 1, "key" : { "_id" : 1 }, "ns" : "mydb.foo", "name" : "_id_" }
+   { "v" : 1, "key" : { "name" : 1 }, "ns" : "mydb.foo", "name" : "name_1" }
+   db.foo.dropIndex({name:1})
+   { "nIndexesWas" : 2, "ok" : 1 }
+
+   // create a v:0 index
+   db.foo.ensureIndex({name:1},{v:0})
+   db.system.indexes.find()
+   { "v" : 1, "key" : { "_id" : 1 }, "ns" : "mydb.foo", "name" : "_id_" }
+   
+   { "v" : 0, "key" : { "name" : 1 }, "ns" : "mydb.foo", "name" : "name_1" }
+
+.. seealso:: :ref:`2.0-new-index-format` and :ref:`2.0-convert-to-new-index-format`