Skip to content

DOCS-330: editing and resolving todos raised by technical review #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 20, 2012
Merged

DOCS-330: editing and resolving todos raised by technical review #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2eac86c
DOCS-330: editing and resolving todos raised by technical review
Jul 19, 2012
2e6a1b8
DOCS-330 adding examples based on feedback from astaple
Jul 20, 2012
1dd4f9a
DOCS-330 final round of comments on the indexing documents
Jul 20, 2012
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 86 additions & 126 deletions draft/administration/indexes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,7 @@ of the ``people`` collection:

.. code-block:: javascript

db.people.ensureIndex( { phone-number: 1 } )

TODO: you need ""s around phone-number, otherwise it's invalid JS (phone minus number).
db.people.ensureIndex( { "phone-number": 1 } )

To create a :ref:`compound index <index-type-compound>`, use an
operation that resembles the following prototype:
Expand All @@ -57,21 +55,18 @@ collection:

db.products.ensureIndex( { item: 1, category: 1, price: 1 } )

.. note::

To build indexes for a :term:`replica set`, before version 2.2,
see :ref:`index-building-replica-sets`.
Some drivers may specify indexes, using ``NumberLong(1)`` rather than
``1`` as the specification. This does not have any affect on the
resulting index.

TODO: I don't think anything changed about replica set index builds for 2.2...
.. include:: /includes/note-build-indexes-on-replica-sets.rst

.. [#ensure] As the name suggests, :func:`ensureIndex() <db.collection.ensureIndex()>`
only creates an index if an index of the same specification does
not already exist.

Sparse
``````

TODO: Sparse? Maybe "Types of Indexes->Sparse"?
Sparse Indexes
``````````````

To create a :ref:`sparse index <index-type-sparse>` on a field, use an
operation that resembles the following prototype:
Expand All @@ -91,16 +86,13 @@ without the ``twitter_name`` field.

.. note::

MongoDB cannot create sparse compound indexes.
Sparse indexes can affect the results returned by the query,
particularly with respect to sorts on fields *not* included in the
index. See the :ref:`sparse index <index-type-sparse>` section for
more information.

TODO: is this true? I thought that it could.

TODO: Is there more doc on spare indexes somewhere? Seems like this is missing
some info like getting different results back when the index is used, null
counts as existing, etc.

Unique
``````
Unique Indexes
``````````````

To create a :ref:`unique indexes <index-type-unique>`, consider the
following prototype:
Expand All @@ -109,21 +101,17 @@ following prototype:

db.collection.ensureIndex( { a: 1 }, { unique: true } )

For example, you may want to create a unique index on the ``tax-id:``
For example, you may want to create a unique index on the ``"tax-id":``
of the ``accounts`` collection to prevent storing multiple account
records for the same legal entity:

.. code-block:: javascript

db.accounts.ensureIndex( { tax-id: 1 }, { unique: true } )

TODO: tax-id should be in ""s.
db.accounts.ensureIndex( { "tax-id": 1 }, { unique: true } )

The :ref:`_id index <index-type-primary>` is a unique index. In some
situations you may want to use the ``_id`` field for these primary
data rather than using a unique index on another field.

TODO: "for these primary data"?
situations you may consider using ``_id`` field itself for this kind
of data rather than using a unique index on another field.

In many situations you will want to combine the ``unique`` constraint
with the ``sparse`` option. When MongoDB indexes a field, if a
Expand Down Expand Up @@ -155,11 +143,9 @@ as in the following example:

.. code-block:: javascript

db.accounts.dropIndex( { tax-id: 1 } )
db.accounts.dropIndex( { "tax-id": 1 } )

TODO: ""s!

This will remove the index on the ``tax-id`` field in the ``accounts``
This will remove the index on the ``"tax-id"`` field in the ``accounts``
collection. The shell provides the following document after completing
the operation:

Expand Down Expand Up @@ -216,16 +202,7 @@ This shell helper provides a wrapper around the :dbcommand:`reIndex`
</applications/drivers>` may have a different or additional interface
for this operation.

.. note::

To rebuild indexes for a :term:`replica set`, before version 2.2,
see :ref:`index-rebuilding-replica-sets`.

TODO: again, this probably isn't different in 2.2

TODO: one thing that I would appreciate you mentioning is that some drivers may
create indexes like {a : NumberLong(1)} _which is fine_ and doesn't break
anything so stop complaining about it.
.. include:: /includes/note-build-indexes-on-replica-sets.rst

Special Creation Options
~~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -235,7 +212,8 @@ Special Creation Options
TTL collections use a special ``expire`` index option. See
:doc:`/tutorial/expire-data` for more information.

TODO: Are 2d indexes getting a mention?
.. TODO: insert link here to the geospatial index documents when
they're published.

Background
``````````
Expand All @@ -248,26 +226,17 @@ prototype invocation of :func:`db.collection.ensureIndex()`:

db.collection.ensureIndex( { a: 1 }, { background: true } )

TODO: what does it mean to build an index in the background? You might want to
mention:
* performance implications
* that this type of index build can be killed
* that this blocks the connection you sent the ensureindex on, but ops from
other connections can proceed in
* that indexes are created on the foreground on secondaries in 2.0,
which blocks replication & slave reads. In 2.2, it does not block reads (but
still blocks repl).
Consider the section on :ref:`background index construction
<index-creation-background>` for more information about these indexes
and their implications.

Drop Duplicates
```````````````

To force the creation of a :ref:`unique index <index-type-unique>`
index

TODO: " on a collection with duplicate values in the field to be indexed "

you can use the ``dropDups`` option. This will force MongoDB to
create a *unique* index by deleting documents with duplicate values
index on a collection with duplicate values in the field you are
indexing you can use the ``dropDups`` option. This will force MongoDB
to create a *unique* index by deleting documents with duplicate values
when building the index. Consider the following prototype invocation
of :func:`db.collection.ensureIndex()`:

Expand All @@ -280,82 +249,63 @@ See the full documentation of :ref:`duplicate dropping

.. warning::

Specifying ``{ dropDups: true }`` will delete data from your
Specifying ``{ dropDups: true }`` may delete data from your
database. Use with extreme caution.

TODO: I'd say it "may" delete data from your DB, not like it's going to go all
Shermanesque on your data.

.. _index-building-replica-sets:

Building Indexes on Replica Sets
--------------------------------

.. versionchanged:: 2.2
Index rebuilding operations on :term:`secondary` members of
:term:`replica sets <replica set>` now run as normal background
index operations. Run :func:`ensureIndex()
<db.collection.ensureIndex()>` normally with the ``{ background:
true }`` option for replica sets. Alternatively, you may always use
the following operation to isolate and control the impact of
indexing building operations on a set as a whole.

TODO: I think there needs to be a huge mention that this still blocks
replication, so the procedure below is recommended.

.. admonition:: For Version 1.8 and 2.0

:ref:`Background index creation operations
<index-creation-background>` became *foreground* indexing
operations on :term:`secondary` members of replica sets. These
foreground operations will block all replication on the
secondaries,
Consideration
~~~~~~~~~~~~~

TODO: and don't allow any reads to go through.
:ref:`Background index creation operations
<index-creation-background>` become *foreground* indexing operations
on :term:`secondary` members of replica sets. These foreground
operations will block all replication on the secondaries, and don't
allow any reads. As a result in most cases use the following procedure
to build indexes on secondaries.

and can impact performance of the entire set. To build
indexes with minimal impact on a replica set, use the following
procedure for all non-trivial index builds:
Procedure
~~~~~~~~~

#. Stop the :program:`mongod` process on one secondary. Restart the
:program:`mongod` process *without* the :option:`--replSet <mongod --replSet>`
option. This instance is now in "standalone" mode.
#. Stop the :program:`mongod` process on one secondary. Restart the
:program:`mongod` process *without* the :option:`--replSet <mongod --replSet>`
option and running on a different port. [#different-port]_ This
instance is now in "standalone" mode.

TODO: generally we recommend running it on a different port, too, so that apps
& other servers in the set don't try to contact it.
#. Create the new index or rebuild the index on this :program:`mongod`
instance.

#. Create the new index or rebuild the index on this :program:`mongod`
instance.
#. Restart the :program:`mongod` instance with the
:option:`--replSet <mongod --replSet>` option. Allow replication
to catch up on this member.

#. Restart the :program:`mongod` instance with the
:option:`--replSet <mongod --replSet>` option. Allow replication
to catch up on this member.
#. Repeat this operation on all of the remaining secondaries.

#. Replete this operation on all of the remaining secondaries.
#. Run :func:`rs.stepDown()` on the :term:`primary` member of the
set, and then repeat this procedure on the former primary.

#. Run :func:`rs.stepDown()` on the :term:`primary` member of the
set, and then run this procedure on the former primary.

.. warning::
.. warning::

Ensure that your :ref:`oplog` is large enough to permit the
indexing or re-indexing operation to complete without falling
too far behind to catch up. See the ":ref:`replica-set-oplog-sizing`"
documentation for additional information.
Ensure that your :ref:`oplog` is large enough to permit the
indexing or re-indexing operation to complete without falling
too far behind to catch up. See the ":ref:`replica-set-oplog-sizing`"
documentation for additional information.

.. note::
.. note::

This procedure *does* block indexing on one member of the
replica set at a time. However, the foreground indexing
operation is more efficient than the background index operation,
and will only affect one secondary at a time rather than *all*
secondaries at the same time.
This procedure *does* take one member out of the replica set at a
time. However, this procedure will only affect one member of the
set at a time rather than *all* secondaries at the same time.

For the best results, always create indexes *before* you begin
inserting data into a collection.
.. [#different-port] By running the :program:`mongod` on a different
port, you ensure that the other members of the replica set and all
clients will not contact the member while you are building the
index.

TODO: well, sort of. That'll build the indexes fast, but make the inserts
slower. Overall, it's faster to insert data, then build indexes.
.. _indexes-measuring-use:

Measuring Index Use
-------------------
Expand All @@ -374,31 +324,41 @@ following tools:
- :func:`cursor.hint()`

Append the :func:`hint() <cursor.hint()>` to any cursor (e.g.
query) with the name

TODO: this isn't "the name of an index." I'd say just "with the index." The
name of an index is a string like "zipcode_1".

of an index as the argument to *force* MongoDB
query) with the index as the argument to *force* MongoDB
to use a specific index to fulfill the query. Consider the following
example:

.. code-block:: javascript

db.people.find( { name: "John Doe", zipcode: { $gt: 63000 } } } ).hint( { zipcode: 1 } )


You can use :func:`hint() <cursor.hint()>` and :func:`explain()
<cursor.explain()>` in conjunction with each other to compare the
effectiveness of a specific index.
effectiveness of a specific index. Specify the ``$natural`` operator
to the :func:`hint() <cursor.hint()>` method to prevent MongoDB from
using *any* index:

.. code-block:: javascript

TODO: mention $natural to force no index usage?
db.people.find( { name: "John Doe", zipcode: { $gt: 63000 } } } ).hint( { $natural: 1 } )

- :status:`indexCounters`

Use the :status:`indexCounters` data in the output of
:dbcommand:`serverStatus` for insight into database-wise index
utilization.

TODO: I'd like to see this also cover how to track how far an index build has
gotten and how to kill an index build.
Monitoring and Controlling Index Building
-----------------------------------------

.. TODO insert links to the values in the inprog array following the
completion of DOCS-162

To see the status of the indexing processes, you can use the
:func:`db.currentOp()` method in the :program:`mongo` shell. The value
of the ``query`` field and the ``msg`` field will indicate if the
operation is an index build. The ``msg`` field also indicates the
percent of the build that is complete.

If you need to terminate an ongoing index build, You can use the
:func:`db.killOP()` method in the :program:`mongo` shell.
Loading