DOCS-206 new index faq page

Author: Bob Grabar

source/applications/indexes.txt

@@ -52,14 +52,15 @@ However, if you sometimes query on only one key but and at other times
 query on that key combined with a second key, then creating a
 :ref:`compound index <index-type-compound>` is more efficient. MongoDB
 will use the compound index for both queries. For example, you might
-create an index on both ``category`` and ``item``, allowing you both
-options: to query only on ``category`` and also to query on ``category``
-combined with ``item``:
+create an index on both ``category`` and ``item``.
 
 .. code-block:: javascript
 
    db.products.ensureIndex( { "category": 1, "item": 1 } )
 
+This allows you both options. You can query on just ``category``, and
+you also can query on ``category`` combined with ``item``.
+
 To query on multiple keys and sort the results, see :ref:`index-sort`.
 
 With the exception of queries that use the :operator:`$or` operator, a
@@ -68,6 +69,50 @@ query cannot use multiple indexes. A query must use only one index.
 .. _covered-queries:
 .. _indexes-covered-queries:
 
+
+Use Compound Indexes to Support Several Different Queries
+---------------------------------------------------------
+
+A single :ref:`compound index <index-type-compound>` on multiple fields
+can support all the queries that search a "prefix" subset of those fields.
+
+.. example::
+
+   The following index on a collection:
+
+   .. code-block:: javascript
+
+      { x: 1, y: 1, z: 1 }
+
+   Can support queries that the following indexes support:
+
+   .. code-block:: javascript
+
+      { x: 1 }
+      { x: 1, y: 1 }
+
+   There are some situations where the prefix indexes may offer better
+   query performance: for example if ``z`` is a large array.
+
+   The ``{ x: 1, y: 1, z: 1 }`` index can also support many of the same
+   queries as the following index:
+
+   .. code-block:: javascript
+
+      { x: 1, z: 1 }
+
+   Also, ``{ x: 1, z: 1 }`` has an additional use. Given the following
+   query:
+
+   .. code-block:: javascript
+
+      db.collection.find( { x: 5 } ).sort( { z: 1} )
+
+   The ``{ x: 1, z: 1 }`` index supports both the query and the sort
+   operation, while the ``{ x: 1, y: 1, z: 1 }`` index only supports
+   the query. For more information on sorting, see
+   :ref:`sorting-with-indexes`.
+
 Create Indexes that Support Covered Queries
 -------------------------------------------
 
@@ -183,28 +228,19 @@ available but also must have RAM available for the rest of the
 :term:`working set`. Also remember:
 
 - If you have and use multiple collections, you must consider the size
-  of all indexes on all collections.
+  of all indexes on all collections. The indexes and the working set must be able to
+  fit RAM at the same time.
 
-- There are some limited cases where indexes do not need to fit in RAM.
-  See :ref:`indexing-right-handed`.
+- All of your indexes use less space than all of the documents in the
+  collection. This may not be an issue if all your queries use
+  :ref:`covered queries <covered-queries>` or if indexes do not need to
+  fit into RAM. There are some limited cases where indexes do not need
+  to fit in RAM. See :ref:`indexing-right-handed`.
 
 .. seealso:: For additional :doc:`collection statistics
    </reference/collection-statistics>`, use :dbcommand:`collStats` or
    :method:`db.collection.stats()`.
 
-Indexes require space, both on disk and in RAM. Indexes require less
-space in RAM than the full documents in the collection. In theory, if
-your queries only match a subset of the documents and can use the index
-to locate those documents, MongoDB can maintain a much smaller
-:term:`working set`. Ensure that:
-
-- The indexes and the working set can fit RAM at the same time.
-
-- All of your indexes use less space than all of the documents in the
-  collection. This may not be an issue all of your queries use
-  :ref:`covered queries <covered-queries>` or indexes do not need to fit
-  into ram, as in the following situation:
-
 .. _indexing-right-handed:
 
 Indexes that Hold Only Recent Values in RAM
@@ -218,17 +254,14 @@ RAM. This allows for efficient index use for read and write
 operations and minimize the amount of RAM required to support the
 index.
 
-.. To determine the size of the index, see DOCS-224
-
 .. _index-selectivity:
 
 Create Queries that Ensure Selectivity
 --------------------------------------
 
-Selectivity is the ability of a query to narrow results
-using the index. Effective indexes are more selective and allow
-MongoDB to use the index for a larger portion of the work associated
-with fulfilling the query.
+Selectivity is the ability of a query to narrow results using the index.
+Effective indexes are more selective and allow MongoDB to use the index
+for a larger portion of the work associated with fulfilling the query.
 
 To ensure selectivity:
 
@@ -322,70 +355,27 @@ Consider Insert Throughput
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. TODO insert link to /source/core/write-operations when that page is complete.
+   Do we want to link to write concern? -bg
 
-MongoDB must update all indexes associated with a collection after
-every insert, update, or delete operation.
-
-Every index on a collection adds some amount of overhead to these
-operations. In almost every case, the performance gains that indexes
-realize for read operations are worth the insertion penalty; however:
-
-- In some cases, an index to support an infrequent query may incur
-  more insert-related costs than saved read-time.
-
-- In some situations, if you have many indexes on a collection with a
-  high insert throughput and a number of very similar indexes, you may
-  find better overall results by using a slightly less effective index
-  on some queries if it means consolidating the total number of
-  indexes.
-
-- If your indexes and queries are not very selective, the speed
-  improvements for query operations may not offset the costs of
-  maintaining an index. See the section on :ref:`index selectivity
-  <index-selectivity>` for more information.
-
-- In some cases a single compound on two or more fields index may
-  support all of the queries that index on a single field index, or a
-  smaller :ref:`compound index <index-type-compound>`. In general,
-  MongoDB can use compound index
-  to support the same queries as any of its prefixes. Consider the
-  following example:
-
-  .. example::
-
-     Given the following index on a collection:
-
-     .. code-block:: javascript
-
-        { x: 1, y: 1, z: 1 }
-
-     Can support a number of queries as well as most of the queries
-     that the following indexes support:
-
-     .. code-block:: javascript
-
-        { x: 1 }
-        { x: 1, y: 1 }
-
-     There are some situations where the prefix indexes may offer
-     better query performance as is the case if ``z`` is a large
-     array. Also, consider the following index on the same collection:
-
-     .. code-block:: javascript
-
-        { x: 1, z: 1 }
+MongoDB must update all indexes associated with a collection after every
+insert, update, or delete operation. Therefore, every index on a
+collection adds some amount of overhead to these operations. In almost
+every case, the performance gains that indexes realize for read
+operations are worth the insertion penalty. However, in some cases:
 
-     The ``{ x: 1, y: 1, z: 1 }`` index can support many of the same
-     queries as the above index; however, ``{ x: 1, z: 1 }`` has
-     additional use: Given the following query:
+- An index to support an infrequent query might incur more
+  insert-related costs than saved read-time.
 
-     .. code-block:: javascript
+  .. TODO How do you determine if the above is the case?
 
-        db.collection.find( { x: 5 } ).sort( { z: 1} )
+- If you have many indexes on a collection with a high insert throughput
+  and a number of very similar indexes, you may find better overall
+  results by using a slightly less effective index on some queries if it
+  means consolidating the total number of indexes.
 
-     The ``{ x: 1, z: 1 }`` will support both the query and the sort
-     operation, while the ``{ x: 1, y: 1, z: 1 }`` index can only
-     support the query.
+  .. TODO The above is unclear. -bg
 
-     See the :ref:`sorting-with-indexes` section for more
-     information.
+- If your indexes and queries are not very :ref:`selective
+  <index-selectivity>`, the speed improvements for query operations
+  might not offset the costs of maintaining an index. For more
+  information see :ref:`index-selectivity`.

source/faq/indexes.txt

@@ -25,9 +25,68 @@ changes.
 While running :method:`ensureIndex() <db.collection.ensureIndex()>` is
 usually ok, if an index doesn't exist because of ongoing administrative
 work, a call to :method:`ensureIndex() <db.collection.ensureIndex()>`
-may disrupt database avalability. Runnning :method:`ensureIndex() <db.collection.ensureIndex()>`
-can render a replica set inaccessible as the index
-creation is happening. See :ref:`index-building-replica-sets`.
+may disrupt database avalability. Runnning :method:`ensureIndex()
+<db.collection.ensureIndex()>` can render a replica set inaccessible as
+the index creation is happening. See :ref:`index-building-replica-sets`.
+
+How do you know what indexes exist in a collection?
+---------------------------------------------------
+
+To list a collection's indexes, use the
+:method:`db.collection.getIndexes()` method or a similar
+:api:`method for your driver <>`.
+
+How do you determine the size of an index?
+------------------------------------------
+
+To check index size, use :method:`db.collection.totalIndexSize()`.
+
+.. TODO FAQ How do I determine if an index fits into RAM?
+
+What happens if an index does not fit into RAM?
+-----------------------------------------------
+
+When an index is too large to fit into RAM, MongoDB must read the index
+from disk, which is a much slower operation than reading from RAM. Keep
+in mind an index fits into RAM when your server has RAM available for
+the index combined with the rest of the :term:`working set`.
+
+In certain cases, an index does not need to fit *entirely* into RAM. For
+details, see :ref:`indexing-right-handed`.
+
+.. TODO FAQ How does MongoDB determine what index to use?
+
+How do you know what index a query used?
+----------------------------------------
+
+To determine how a query is processed, use the :method:`explain()
+<cursor.explain()>` method.
+
+How do you determine what fields to index?
+------------------------------------------
+
+A number of factors determine what fields to index, including
+:ref:`selectivity <index-selectivity>`, fitting indexes into RAM,
+reusing indexes in multiple queries when possible, and creating indexes
+that can support all the fields in a given query. For detailed
+documentation on choosing which fields to index, see
+:doc:`/applications/indexes`.
+
+.. TODO FAQ How do I guarantee a query uses an index?
+   MongoDB's query optimizer always looks for the most advantageous
+   index to use. You cannot guarantee use of a particular index, but you
+   can write indexes with your queries in mind. For detailed
+   documentation on creating optimal indexes, see
+   :doc:`/applications/indexes`.
+
+How do write operations affect indexes?
+---------------------------------------
+
+While a read operation does not affect an index, every write operation
+does involve a write to the index. If your application is write-heavy,
+creating too many indexes might affect performance.
+
+.. TODO More is needed on that last FAQ.
 
 Will building a large index affect database performance?
 --------------------------------------------------------