Compact Redirection and Operator Reference Edits

source/includes/note-ref-equality.rst

@@ -0,0 +1,18 @@
+.. note::
+
+   To express ``equal to`` (e.g. ``=``) in the MongoDB query language,
+   use JSON ``{ key:value }`` structure. Consider the following
+   prototype:
+
+   .. code-block:: javascript
+
+      db.collection.find( { field: value } )
+
+   For example: 
+
+   .. code-block:: javascript
+
+      db.collection.find( { a: 42 } )
+
+   This query selects all the documents the where the ``a`` field
+   holds a value of ``42``.

source/reference/command/compact.txt

@@ -6,52 +6,146 @@ compact
 
 .. dbcommand:: compact
 
+   .. versionadded:: 2.0
+
    The :dbcommand:`compact` command rewrites and defragments a single
-   collection. Additionally, the command forces all indexes on the collection
-   to be rebuilt. The command has the following syntax:
+   collection. Additionally, the command drops all indexes at the
+   beginning of compaction and rebuilds the indexes at the end.
+   :dbcommand:`compact` is conceptually similar to
+   :dbcommand:`repairDatabase`, but works on a single collection rather
+   than an entire database.
+
+   The command has the following syntax:
 
    .. code-block:: javascript
 
-      { compact: "users" }
-
-   This command compacts the collection named ``users``. Note the
-   following command behaviors:
-
-   - During a :dbcommand:`compact`, the database blocks all other activity.
-
-   - In a :term:`replica set`, :dbcommand:`compact` will refuse to run on the
-     primary node unless you also specify ``{ force: true }``.
-     For example:
-
-     .. code-block:: javascript
-
-        { compact: "collection", force: true }
-
-   - If you have journaling enabled, your data will be safe even
-     if you kill the operation or restart the server before it has
-     finished. However, you may have to manually rebuild the indexes.
-     Without journaling enabled, the :dbcommand:`compact` command is much less safe,
-     and there are no guarantees made about the safety of your data in the
-     event of a shutdown or a kill.
-
-     .. warning::
-
-        Always have an up-to-date backup before performing server
-        maintenance such as the :dbcommand:`compact` operation.
-
-   - :dbcommand:`compact` requires a small amount of additional disk space while
-     running but unlike :dbcommand:`repairDatabase` it does *not* free
-     space equal to the total size of the collection.
-
-   - the :dbcommand:`compact` command blocks until the operation is
-     complete.
-
-   - :dbcommand:`compact` removes any :term:`padding factor` in the collection,
-     which may impact performance if documents grow regularly.
-
-   - :dbcommand:`compact` commands do not replicate. They must be run on slaves
-     and replica set members independently.
-
-   - It is not possible to compact :term:`capped collections <capped collection>`
-     because they don't have padding, and documents
-     cannot grow in these collections.
+      { compact: <collection name> }
+
+   You may also specify one of the following options:
+
+   - ``force: true`` 
+
+     To run on the primary node in a :term:`replica set`. Otherwise,
+     the :dbcommand:`compact` command returns an error when invoked on
+     a :term:`replica set` primary because the command blocks all other
+     activity.
+
+     .. versionchanged:: 2.2 :dbcommand:`compact` blocks activities only
+         for its database.
+
+   - ``paddingFactor: <factor>``
+
+     To specify a :term:`padding factor` ranging from 1.0 to 4.0 for
+     the compacted documents. Default factor is 1.0, specifying no
+     padding and the maximum padding factor is 4.0. If you do updates
+     that increase the size of the documents, you will want some
+     padding, especially if you have several indexes for the collection.
+
+     .. versionadded:: v2.2
+
+   - ``paddingBytes: <bytes>`` 
+
+     To specify a padding as an absolute number of bytes. Specifying
+     ``paddingBytes`` can be useful if your documents start small but
+     then increase in size significantly. For example,if your documents
+     are initially 40 bytes long and you grow them by 1KB, using
+     ``paddingBytes: 1024`` might be reasonable since using
+     ``paddingFactor: 4.0`` would only add 40 * (4.0 - 1) = 120 bytes
+     of padding.
+
+     .. versionadded:: v2.2
+
+   It is recommended that you always add at least 100 bytes of padding,
+   and at least 10% of the doc size.
+
+   .. code-block:: javascript
+
+      db.runCommand ( { compact: 'collection name', paddingBytes: 100, paddingFactor: 1.1 } )
+
+   .. warning::
+
+      Always have an up-to-date backup before performing server
+      maintenance such as the :dbcommand:`compact` operation.  
+
+   Note the following command behaviors:
+
+   - :dbcommand:`compact` blocks all other activity (in v2.2, blocks
+     activities only for its database.) You may view the intermediate
+     progress either by viewing the the :program:`mongod` log file, or
+     by running the :method:`db.currentOp()` in another shell instance.
+
+   - :dbcommand:`compact` removes any :term:`padding factor` in the
+     collection if the command is run without either the
+     ``paddingFactor`` option or the ``paddingByte`` option. This may
+     impact performance if the documents grow regularly. However, the
+     existing paddingFactor statistics is kept for the collection and
+     will be used for future inserts.
+
+   - :dbcommand:`compact` generally uses less disk space than
+     :dbcommand:`repairDatabase` and is faster. However,the
+     :dbcommand:`compact` command is still slow and does block database
+     activities, so you should run the command during scheduled
+     maintenance.
+
+   - If you kill the operation by running the :method:`db.killOp(opid) <db.killOP()>`  or
+     restart the server before it has finished:
+
+     + If you have journaling enabled, your data will
+       be safe. However, you may have to manually rebuild the indexes.
+
+     + If you do not have journaling enabled, the :dbcommand:`compact`
+       command is much less safe, and there are no guarantees made about
+       the safety of your data in the event of a shutdown or a kill.
+
+     + In either case, much of the existing free space in the
+       collection may become un-reusable. In this scenario, you should
+       rerun the compaction to completion to restore the use of this free
+       space.
+
+   - :dbcommand:`compact` may increase the total size and number of our
+     data files, expecially when run for the first time. However, this
+     will not increase the total colletion storage space since storage
+     size is the amount of data allocated within the database files,
+     and not the size/number of the files on the file system.
+
+   - :dbcommand:`compact` requires a small amount of additional disk
+     space while running but unlike :dbcommand:`repairDatabase` it does
+     *not* free space on the file system. 
+
+   - You may also wish to run the :dbcommand:`collstats` command before and
+     after compaction to see how the storage space changes for the
+     collection.
+
+   - :dbcommand:`compact` commands do not replicate. When running
+     compact on a :term:`replica set`: 
+
+     + Compact each member separately. 
+
+     + Ideally, compaction runs on a secondary. (See option
+       ``force:true`` above for information regarding compacting the
+       primary.)
+
+     + If :dbcommand:`compact` runs on a secondary, the secondary will
+       go into "recovering" state automatically to prevent reads from
+       being routed to it during compation. Once the compaction is
+       finished, it will automatically return to secondary state.
+
+       You may refer to the "`partial script for automating step down
+       and compaction
+       <https://github.com/mongodb/mongo-snippets/blob/master/js/compact
+       -example.js>`_") for an example.
+
+   - :dbcommand:`compact` is a command issued to a :program:`mongod`.
+     In a sharded environment, run :dbcommand:`compact` on each shard
+     separately as a maintenance operation. (This will likely change in
+     the future with other enhancements.)
+
+   - It is not possible to compact :term:`capped collections <capped
+     collection>` because they don't have padding, and documents cannot
+     grow in these collections. However, the documents of a
+     :term:`capped collections <capped collection>` are not subject o
+     fragmentation.
+
+   .. seealso:: 
+
+      :dbcommand:`repairDatabase`

source/reference/operator/all.txt

@@ -6,21 +6,54 @@ $all
 
 .. operator:: $all
 
-   The :operator:`$all` operator matches a minimum set of elements that must
-   be present in a document's ``field``, as in the following example:
+   *Syntax*: ``{ field: { $all: [ <value> , <value1> ... ] }``
+
+   :operator:`$all` selects the documents where the ``field`` holds an
+   array and contains all elements (e.g. ``<value>``, ``<value1>``, etc.)
+   in the array.
+
+   Consider the following example:
+
+   .. code-block:: javascript
+
+      db.inventory.find( { tags: { $all: [ "appliances", "school", "book" ] } } )
+
+   This query selects all documents in the ``inventory`` collection
+   where the ``tags`` field contains an array with the elements,
+   ``appliances``, ``school``, and ``technology``. 
 
+   Therefore, the above query will match documents in the ``inventory``
+   collection that have a ``tags`` field that hold *either* of the
+   following arrays:
+
+   .. code-block:: javascript
+
+      [ "school", "book", "bag", "headphone", "appliances" ]
+      [ "appliances", "school", "book" ]
+
+   The :operator:`$all` operator exists to describe and specify arrays
+   in MongoDB queries. However, you may use the :operator:`$all`
+   operator to select against a non-array ``field``, as in the
+   following example:
+
    .. code-block:: javascript
+
+      db.inventory.find( { qty: { $all: [ 50 ] } } )
+
+   **However**, use the following form to express the same query: 
 
-      db.collection.find( { field: { $all: [ 1, 2 , 3 ] } } );
+   .. code-block:: javascript
+
+      db.inventory.find( { qty: 50 } )
 
-   This returns all documents in ``collection`` where the value of
-   ``field`` is an array that is equivalent to or a superset of ``[
-   1, 2, 3, ]``. The :operator:`$all` operator will not return any arrays
-   that are subsets; for example, the above query matches ``{ field: [
-   1, 2, 3, 4] }`` but not ``{ field: [ 2, 3 ] }``.
+   Both queries will select all documents in the ``inventory``
+   collection where the value of the ``qty`` field equals ``50``.
 
    .. note::
 
       In most cases, MongoDB does not treat arrays as sets. This
-      operator provides a notable exception to this general approach
-
+      operator provides a notable exception to this approach.
+
+   .. seealso:: 
+      :method:`find() <db.collection.find()>`, :method:`update()
+      <db.collection.update()>`, and :operator:`$set`.

source/reference/operator/and.txt

@@ -8,14 +8,51 @@ $and
 
    .. versionadded:: 2.0
 
-   The :operator:`$and` operator provides a Boolean ``AND`` expression in
-   queries. Use :operator:`$and` to return the documents that satisfy *all*
-   included expressions. For example:
+   *Syntax*: ``{ $and: [ { <expression1> }, { <expression2> } , ... , { <expressionN> } ] }`` 
+
+   :operator:`$and` performs a logical ``AND`` operation on an array
+   of *two or more* expressions (e.g. ``<expression1>``,
+   ``<expression2>``, etc.) and selects the documents that satisfy
+   *all* the expressions in the array.
 
+   Consider the following example: 
+
    .. code-block:: javascript
+
+      db.inventory.find({ $and: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] } )
 
-      db.collection.find( { $and [ { key1: value1 }, { key2: value2} ] } );
+   This query will select all documents in the ``inventory``
+   collection where:
+
+   - ``price`` field value equals ``1.99`` **and** 
+   - ``qty`` field value is less than ``20`` **and**
+   - ``sale`` field value is equal to ``true``.
 
-   returns all documents in ``collection`` that have *both* a
-   ``key1`` field with ``value1`` *and* a ``key2`` field with
-   ``value2``.
+   MongoDB provides an implicit ``AND`` operation when specifying a
+   comma separated list of expressions. For example, you may write the
+   above query as:
+
+   .. code-block:: javascript
+
+      db.inventory.find( { price: 1.99, qty: { $lt: 20 } , sale: true } )
+
+   If, however, a query requires an ``AND`` operation on the same
+   field, you *must* use the :operator:`$and` operator as in the
+   following example:
+
+   .. code-block:: javascript
+
+      db.inventory.update( { $and: [ { price: { $ne: 1.99 } }, { price: { $exists: true } } ] }, { $set: { qty: 15 } } )
+
+   This :method:`update() <db.collection.update()>` operation will set
+   the value of the ``qty`` field in documents where: 
+
+   -  the ``price`` field value does not equal ``1.99`` **and** 
+   -  the ``price`` field exists.
+
+   .. seealso:: 
+
+      :method:`find() <db.collection.find()>`, :method:`update()
+      <db.collection.update()>`, :operator:`$ne`, :operator:`$exists`,
+      :operator:`$set`.
+

source/reference/operator/exists.txt

@@ -6,19 +6,28 @@ $exists
 
 .. operator:: $exists
 
-   The :operator:`$exists` operator tests documents for the existence
-   of a field. The :operator:`$exists` operator accepts either true and
-   false values. For example:
+   *Syntax*: ``{ field: { $exists: boolean } }`` 
 
-   .. code-block:: javascript
-
-        db.collection.find( { field: { $exists: true } );
+   :operator:`$exists` selects the documents that contain the field.
+   MongoDB `$exists` does **not** correspond to SQL operator
+   ``exists``. For SQL ``exists``, refer to the :operator:`$in`
+   operator.
 
-   returns all documents in ``collection`` that have ``field``, while:
+   Consider the following example:
 
    .. code-block:: javascript
 
-      db.collection.find( { field: { $exists: false } );
-
-   returns all documents in ``collection`` that do *not* have ``field``
-   specified.
+      db.inventory.find( { $and: [ { qty: { $exists: true } }, { qty: { $nin: [ 5, 15 ] } } ] } )
+
+   This query will select all documents in the ``inventory`` collection
+   where the ``qty`` field exists *and* its value does not equal either
+   ``5`` nor ``15``.
+
+   The above query used the :operator:`$and` operator because the query
+   performs an ``AND`` operation on the value of the same field and is
+   not specific to the :operator:`$exists` operator.
+
+   .. seealso:: 
+
+      :method:`find() <db.collection.find()>`, :operator:`$and`,
+      :operator:`$nin`, :operator:`$in`.